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Preface 


Objectives 


This manual describes directives to the RSTS/E monitor, the RSX emulator, 
and the RT11 emulator that you can use in MACRO programs. To use these 
directives, you should be familiar with the MACRO-11 assembly language. 
MACRO is the standard assembler for DIGITAL PDP-11 computers and is 
available under various operating systems for the PDP-—11. Note that the syntax 
is basically the same for all operating systems. 


Manual Structure 


This manual contains seven chapters and two appendixes: 


Chapter 1 
Chapter 2 
Chapter 3 
Chapter 4 
Chapter 5 


Chapter 6 
Chapter 7 


Appendix A 
Appendix B 


Gives an overview of run-time systems and jobs as they relate to the 
system directives. 


Describes the RSTS/E environment (memory allocation and job space) for 
the general monitor directives. 


Contains reference material for the general monitor directives that you 
can use in programs compiled under either the RSX or RT11 run-time 
systems. 


Describes the RSX environment for the RSX directives. 


Contains reference material for the directives processed by the RSX 
emulator or the RSX run-time system. 


Describes the RT11 environment for the RT11 directives. 


Contains reference material for the directives processed by the RT11 
emulator in the RT11 run-time system. 


Lists the RSTS/E errors you can get during directive processing. 


Summarizes MODE and RECORD values and other useful information 
for disks, flexible diskettes, magnetic tape, line printers, terminals, and 
pseudo keyboards. 
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Related Documents 


For information about the syntax of MACRO assembly language, see the PDP—11 
MACRO-11 Language Reference Manual. 


Where appropriate, this manual references the following manuals from the RSTS 
/E documentation set: 


RSTS/E System Installation and Update Guide 
RSTS/E System Manager’s Guide 

RSTS/E System User’s Guide 

BASIC-PLUS Language Manual 

RSTS/E Programming Manual 

RSTS /E Programmer’s Utilities Manual 
RSTS/E Task Builder Reference Manual 


Conventions 


Xiv 


This manual uses the following conventions: 


—> The arrow means points to, or contains the address of, as when the stack 
pointer register points to the first item in the stack. For example: 
SP— item at top of stack 
item one word down from top of stack 


() Parentheses mean the contents of the item that the parentheses surround. For 
example, the contents of the program counter would be represented as: 
(PC) 
[] Brackets around an item indicate that the item is optional. For example: 


QIO$ param1 [,param2] 


{} Braces around two or more items indicate that you must choose one of the 
enclosed items. For example: 


{ Grows } 


<> Angle brackets around two or more items tell the MACRO assembler that the 
items make up a list. For example: 


GLOBAL<namel|[,name?2....]> 


Summary of Technical Changes for V10.0 


Significant changes to the RSTS/E System Directives Manual are: 


Allowable pack cluster sizes now go up to 64. See Appendix B. 


RSTS/E now supports the RA70, RA90, RD31, RD32, RD53, and RD54 disk 
drives. See Chapter 2. 


RSTS/E now supports online creation and deletion of the virtual disk (device 
DV0:). See Chapter 3, the section ".UUO—Execute BASIC-PLUS SYS Call," 
the subsection "UU.RTS." 


RSTS/E now supports Local Area Transport (LAT) for both in-bound and 
host-initiated connections. See Chapter 3, the section ".:MESAG—Message 
Send/Receive." | 


RSTS/E now supports command recall and command line editing. See 
Chapter 3, the section ".UUO—Execute BASIC-PLUS SYS Call," the sub- 
section "UU.TRM." 


RSTS/E now has a new in-memory structure called the job header, used 
for user logical names and command line editing information. See Chapter 
2 and Chapter 3, the sections "FSS—Check File Specification String" and 
UU.ASS—Allocate/Reallocate a Device, or Assign or List User Logical." 


RSTS/E now supports extended user and system logical names. See Chapter 
2 and Chapter 3, the sections "FSS—Check File Specification String" and 
UU.ASS—Allocate/Reallocate a Device, or Assign or List User Logical." 


You can now use the UU.FIL call to control a files BACKUP and IGNORE 
bits. See Chapter 3, the section ".UUO—Execute BASIC-PLUS SYS Call," the 
subsection "UU.FIL." | 


RSTS/E now supports floating resident libraries. See Chapter 3, the section 
" UUO—Execute BASIC-PLUS SYS Call,” the subsection "UU.RTS." 


You can now use the UU.CFG call to set Answerback messages for electronic 
messaging services such as TELEX and TWX. See Chapter 3, the section 
",UUO — Execute BASIC-PLUS SYS Call," the subsection "UU.CFG." 


RSTS/E now supports the new RSX emulator directives, EXTM$, FEADF$, 
FEAT$, MSDS$, SSTX$, TFEA$, and the fast-mapping facility. See Chapter 5. 
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Chapter 1 


Introduction 


There are two MACRO assemblers available for the run-time systems on RSTS/E: 
one for RSX and one for RT-11. You will use one of these two run-time systems 
to assemble and, in most cases, run your programs. In addition to user programs, 


you can also write or modify run-time systems that run under direct control of 
the RSTS/E monitor. 


This manual describes the three types of system directives available to RSTS/E 
assembly language programmers: 


¢ General monitor directives 
e RSX emulator directives 


e RT-11 emulator directives 


Before you start using these directives, it is helpful to understand some basic 
concepts about RSTS/E run-time systems and jobs. 


1.1 Run-Time Systems 


1.1.1 


A run-time system lets you write code that can be shared by many users when 
it is in memory. In a time-sharing system such as RSTS/E, shareable code is an 
important consideration. 


Run-time systems are normally written as pure (or shareable) code. This means 
they have only instructions and fixed data, and contain no variable data. Such 
code saves space, since many jobs can use it. It also saves time since run-time 
systems are not swapped in and out of memory like user programs. Because the 
run-time systems contain no variable data, they do not need to be swapped out to 
disk; they are simply reloaded when they are needed again. 


User Environment 


The DCL, BASIC-PLUS, RSX, and RT-11 run-time systems all have a keyboard 
monitor. That is, they can accept, analyze, and act on commands you type at a 
terminal keyboard. The RSTS/E System User’s Guide gives an overview of the 
user environment these run-time systems provide. 
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1.1.2 Program Environment 


1.1.2.1 
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Run-time systems also provide an environment for programs. A run-time system 
may include: 


e <A loader. This code loads a program from disk into memory and starts its 
execution. 


e An emulator. This code emulates directives handled by Digital’s RT—11 
operating system for the PDP—11 computer. 


e A command interpreter. This code receives command lines from the user and 
acts on them. 


NOTE 


The RSX run-time system provides only a user (command) environ- 
ment. Both the program loader and the emulation functions for the 
RSX environment are built into the RSTS/E V10.0 monitor. 


A run-time system usually takes up space in the 34K-word area called the user 
job area. Therefore, it limits the size of your program to less than 32K words. 
The RT-11 run-time system takes 4K words of virtual memory. Since the monitor 
emulates the RSX directives, programs running under the RSX run-time system 
do not give up any addressing space. Chapter 2 explains space requirements in 
greater detail. 


Should you program under the RSX or RT-11 run-time system? RSX is usually a 
better choice because it is in the monitor and it offers easy access to most resident 
libraries. Your decision depends on: 


e Whether you are coding MACRO subroutines for use in a high-level language 
program 


¢ Which set of program development tools better satisfies your needs 
e Whether you want to use resident libraries 


e Whether you need separate Instruction and Data Space (I&D Space) support 
for programs larger than 32K words 


High-Level Languages 


When you write MACRO subroutines for use in high-level language programs, 
the high-level language dictates which run-time system you must use. BASIC- 
PLUS-2, COBOL-81, PDP-—11 COBOL, DIBOL, and FORTRAN-?77 all run under 
the RSX emulator, while FORTRAN-IV runs under the RT-11 run-time system. 
You must compile, link, and run all the modules in your program under the same 
run-time system, whether your program is written in MACRO or in a high-level 
language. 


1.1.2.2 Program Development Tools 


As Table 1-1 shows, RSTS/E anegiten one set of program devSteoment tools for 
the RSX environment and another set for the RT—11 environment. 


Table 1-1: RSX and RT-11 Development Tools 


Tool RSX RT-11 
Assembler = = § MAC MACRO 
Linker TKB LINK | 
Librarian LBR LIBR 
Patch Utility PAT PAT 


While the tools for each environment perform similar functions, they differ in 
their speed and capabilities: 


e Assemblers—RSTS/E supports two MACRO-11 assemblers, the RSX-based 
MAC assembler and the RT—11-based MACRO assembler. The two assemblers 
are nearly identical in function and performance and produce similar output. 


e Linkers—RSTS/E supports two linkers: the Task Builder (TKB) for RSX- 
based programs and LINK for RT-11-based programs. While LINK is faster 
than the Task Builder, the Task Builder is more powerful. It can link much 
larger and more complex overlay structures (including co-trees) than LINK. 
Unlike LINK, the Task Builder has options for linking to resident libraries 
and support for separation of instructions and data. 


e Librarians—RSTS/E provides LBR for RSX-based programs and LIBR for 
RT—11-based programs. You can create object and macro libraries with either 
utility. LBR also lets you create universal libraries, which can contain any 
type of file, including text files. 


e Object module patch utilities—RSTS/E provides a PAT utility for each envi- 
ronment. Both let you update code in a relocatable binary object module. 


For details on these program development tools, see the: 
¢ RSTS/E Task Builder Reference Manual—Describes the Task Builder 


° RSTS/E Programmer’s Utilities Manual—Describes the RSX-based MACRO 
assembler, librarian, and object module patch utilities 


°e RSTS/E RT-11 Utilities Manual—Describes the RT—-11-based MACRO assem- 
bler, librarian, linker, and object module patch utilities | 


¢e PDP-11 MACRO-11 Language arene eee Manual—Describes the MACRO-11 
relocatable assembler 


1.1.2.3 Resident Libraries 


When you program under RSX, you can easily use Digital-supplied resident 
libraries (such as RMS—11 and FMS—11) as well as create your own resident 
libraries. Also, because of the Task Builder’s cluster library feature, many 

resident libraries can share the same virtual address space in your program. 


You can also use resident libraries under the RT-11 emulator, but the coding is 
more difficult. Unlike RSX, you must use .PLAS directives to map and create 
address windows inside your task. Coding these directives can be quite complex. 
The Task Builder, on the other hand, has options that build tables describing 
your task and the window to map, and automatically includes the code to perform 
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the necessary .PLAS directives for you. Thus, RSX is a more practical choice than 
RT-11 if you plan to use resident libraries. 


Instruction and Data Space 


The manipulation of Instruction and Data Space (I&D Space) is an advanced 
programming technique that effectively doubles the user’s virtual address range 
from 32K words to 64K words. The memory management unit in some PDP—11 
processors can relocate data and instruction references with separate base ad- 
dress values. Thus, it is possible to have a user program of 64K words consisting 
of 32K words of pure instructions or procedure code and 64K words of data—all 
within a program’s virtual address range. 


1.1.3 Directives for Each Programming Environment 


RSTS/E has three types of directives: 

e Monitor ("native" RSTS/E directives) 
e RSX emulator 

e¢ RTF11 emulator 


Monitor directives are processed directly by the RSTS/E monitor (see Chapter 3). 
You can assemble monitor directives using either the RSX-based or the RT-11- 
based MACRO assembler, and you can use these directives in both user programs 
and run-time systems. (When you write a program to run under the RT-11 
run-time system, you must precede all monitor directives with a special "prefix 
EMT"; see Chapter 6 for details.) 


The RSX emulator, which is part of the RSTS/E monitor, processes the RSX 
emulator directives. These directives, which have basically the same form and 
function as a subset of the RSX-11M—PLUS operating system monitor directives, 
perform non-file-structured I/O, trap handling, and memory management. 

You must use the RSX-based MAC assembler to assemble the RSX emulator 
directives, and you can use them only in a user program that runs under the RSX 
emulator. Chapters 4 and 5 describe the RSX run-time system environment and 
emulator directives in detail. 


RT—11 emulator directives are processed by the RT—11 emulator, which is in 

the RT—11 run-time system. These directives provide most of the single-job 
programmed requests available to MACRO programmers using the RT-11 
operating system. The RT-11 run-time system also provides directives for the 
RSTS/E environment not available under the RT—11 operating system. You must 
use the RT-11-based MACRO assembler to assemble RT—11 emulator directives; 
you can use them only in a user program that runs under the RT—11 run-time 
system. Chapters 6 and 7 describe the RT—11 run-time system environment and 
emulator directives in detail. 


1.1.4 Writing or Modifying a Run-Time System 
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If you want to modify an existing run-time system or code your own run-time 
system, you can use either assembler. You may find the RT—11-based program- 
ming tools easier to use for this purpose than the RSX-based programming tools, 
mainly because it is easier to link run-time systems with the LINK program than 
with the Task Builder. Run-time systems always have a specific address for their 
top (highest) address. When you use LINK, you can specify the top address the 
first time you link the run-time system. But when you use the Task Builder, you 


have to link your run-time system twice—once to find its size, and again to adjust 
its top address to the value you want. 


Unlike a program, a run-time system can contain monitor directives only, not 
RSX or RT—-11 emulator directives. In addition, you must store the run-time 
system file (the product of assembling and linking) on the system disk in save 
image library (SIL) format. To create a SIL file, use: 


e [1,2]IMAKSIL.TSK—For run-time systems assembled with MAC and linked 
with the Task Builder 


e [1,2)SILUS.SAV—For run-time systems assembled with MACRO and linked 
with LINK. 


1.2 Jobs 


Like run-time systems, you can view "jobs" from several angles. To the RSTS/E 
monitor, a job is a unit of work generally associated with activity at a terminal. 
For example, suppose that a user types a line at a previously inactive terminal. 
The monitor creates a job, assigning a job number and allocating internal tables 
for bookkeeping. The monitor then passes control to a new-user entry point in 
the default keyboard monitor, DCL.RTS. 


The default keyboard monitor has code at this entry point that causes the LOGIN 
program to be loaded from the system disk and executed. LOGIN analyzes what 
was typed and performs the normal log-in dialogue. When LOGIN exits for 

a valid login, control passes to the default keyboard monitor, which waits for 
further input from the terminal. 


The monitor considers running the LOGIN program and the default keyboard 
monitor, and whatever else occurs at the terminal until the user logs out as the 
same job. (If the log-in sequence was not valid, LOGIN exits with the job still 
logged out. The monitor destroys the job and releases the job number. ) 


As a MACRO programmer, your awareness of the job concept probably focuses 
on the work space RSTS/E provides for each job, and the fact that the run-time 
system can take part of this work space. Chapter 2 describes the allocation of 
work space. 
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Chapter 2 


General RSTS/E Environment 


This chapter explains how and why one copy of a run-time system, shared by 
many users, can still take up space in each user’s work area. The sections in this 
chapter and their purposes are: 


e How RSTS/E Allocates Memory: Physical and Virtual Addressing 
This section provides some background on memory accessing in the PDP-—11. 
e Job Space: High Segment and Low Segment 


This section explains how RSTS/E uses memory accessing to define a job 
space for each user to run programs. 


¢ Important Installation Options 


This section briefly describes resident libraries and the special-case 
disappearing RSX run-time system. 


e Low-Segment Details: First 512. Bytes of the Low Segment 


This section gives specifics on how the monitor uses the low 512. bytes of 
virtual address space. 


e High-Segment Details: Pseudovectors 


This section explains how the monitor and the run-time systems use 
pseudovectors to communicate with each other. 


2.1 How RSTS/E Allocates Memory: Physical and Virtual 
Addressing 


All RSTS/E systems use the memory management feature available on PDP-11 
computers. This feature extends the addressable memory range of the PDP-11 
processor by using hardware registers called Active Page Registers (APRs). 


The PDP-11 processor handles 16-bit operand addresses. The PDP-11 is 
byte-addressable, so the address range is from 0 through 2416 -1 (65535 
decimal, 177777 octal), which equals 64K bytes or 32K words. With the memory 
management unit, RSTS/E treats a 16-bit address as a relocatable (virtual) 
address that is combined with information in an APR to form an 18-bit (22-bit, 
for the PDP—11/23+, 11/44, 11/53, 11/70, 11/73, 11/83, 11/84, 11/93, and 11/94) 
physical address. On some PDP-11s (11/44, 11/45, 11/50, 11/53, 11/55, 11/70, 
11/73, 11/83, 11/84, 11/93, and 11/94), the memory management unit gives you 
two areas of 32K words each. You can put code (instructions) in one of these 
areas and data in the other. RSTS/E requires that you write your program using 
special techniques to take advantage of both of these areas. This capability is 
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known as Instruction and Data (I&D) Space. You have to use the RSX tools 
(specifically TKB) to build programs with separate instruction and data sections. 


The PDP-11 Architecture Handbook explains in detail how the APRs function. 
Briefly, an APR consists of two 16-bit registers. These registers define a page 
of contiguous memory. The Page Address Register (PAR) defines the physical 
memory location where the page begins. The Page Descriptor Register (PDR) 
defines, among other things, the maximum length of the page and how you can 
access it (for example, read/write or read-only). 


In Figure 2—1, the virtual address of 72322 (octal) identifies APR 3 and byte 
12322 (octal) of the page defined by APR 3. The PAR of APR 3 indicates a 
starting address of 146000 (octal) for the page. The physical address obtained is 
146000+012322, or 160322 (octal). The byte offset field in the virtual address is 
13 bits long. The maximum size of a page, then, is 213 bytes, or 4096 words. In 
other words, one APR can map a virtual address range of up to 4K words into an 
equal extent of physical memory. 


Figure 2-1 shows how you can combine a virtual address and a PAR to form a 
physical address in memory. 


Figure 2-1: How a Physical Address Is Formed 
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The 16-bit virtual address defines which APR the system uses and the byte offset 
within that page. The system handles the PAR of the indicated APR as though it 
contains bits 6-17 (6-21 for the PDP—11/23+4, 11/24, 11/44, 11/70, 11/73 and 11/84) 
of an 18-bit (or 22-bit) physical address, defining the start of the page. 


The memory management unit on the PDP—11 consists of two sets of APRs; eight 
in each set on machines without I&D Space, 16 in each set on machines with 
separate I&D Space. Since each APR can map a 4K segment of virtual memory 
to physical memory, each set of APRs can provide access to 32K words of physical 
memory on non-I&D Space machines, or 64K words on machines with I&D Space 
capability. 


NOTE 


The PDP-11/44, 11/45, 11/50, 11/53, 11/55, 11/70, 11/73, 11/83, 11/84, 
11/93, and 11/94 have three sets of APRs; the additional set is for 
supervisor mode mapping. RSTS/E supports supervisor mode only 
under the RSX run-time system. Using supervisor mode outside the 
RSX run-time system may cause unpredictable results, including fatal 
aborts. 


The monitor uses one set, called the "kernel mode APRs," to map itself in physical 
memory. It uses the other set, called the "user mode APRs," to map the job that 
is active during the current time slice of time-shared processing. 


Figure 2—2 shows the concept of mapping with the APRs. 
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and 11/94, the RSTS/E monitor can take advantage of a hardware function, called 


I&D Space. This function lets a program separate its ins 


On the PDP 11/44, 11/45, 11/50, 11/53, 11/55 


their own virtual address space. On these processors, there are actually two sets 


of eight APRs for each mode. RSTS/E uses one set to map 
other set to map data. So, instead of 32K ma 


I-Space and 32K of D-Space. 
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The monitor may use this type of mapping, depending on the number of small 


buffers the system manager selects with the INIT option. (The RSTS/E System 


Installation and Update Guide describes INIT.) For example, if the number of 
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requested small buffers is large enough, the monitor may use D-Space APR 1 to 
map small buffers and I-Space APR 1 to map common routines. 


Figure 2—3 shows a task executing on an I&D-Space system without using 
separate 1&D Space. Note how the I-Space APRs and the D-Space APRs point to 
the same physical memory. 


Figure 2-3: Conventional Task Linked to a Library in an 1&D-Space System 
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Figure 2—4 shows a task using separate I&D Space. Note how the task’s I-Space 
APRs and D-Space APRs point to different physical memory. User programs 
can also take advantage of I&D Space to increase their available virtual address 
space. 


Figure 2-4: !&D-Space Task Mapping in an 1&D-Space System 
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2.2 Job Space: High Segment and Low Segment 


The RSTS/E monitor is designed to handle work requested by a user through 

an interface: the run-time system. For example, the BASIC-PLUS, DCL, RSX, 
and RI~11 run-time systems (available as part of a RSTS/E system) each provide 
their own keyboard monitor to accept and process user commands. Some of 
these run-time systems also contain code to handle their own sets of directives, 
accepting and expanding user program calls to the monitor. For example, the 
RT-11 run-time system provides I/O calls to the monitor using the monitor 
requests native to RT-11, which the run-time system translates to the equivalent 
requests known to RSTS/E, which are handled directly by the monitor. 


Thus, the run-time system communicates with both the user program and 
the monitor. Execution control passes back and forth between these three 
independent elements; data is passed between them using established ranges of 
virtual addresses. The monitor must be able to access both the run-time system 
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and the user job image at any given time. The monitor does this by setting up 
the run-time system as part of the 32K words accessible through the eight user 
APRs. i 


The monitor assigns an area for the run-time system in the high portion of virtual 
address space, called the high segment. The user job image (that is, the utility 
program, compiler, assembler, or executable user program that is currently being 
executed for the job) is in the low portion of virtual address space, called the low 
segment. 


NOTE 


If you are using the monitor’s RSX emulation, there is no high segment 
at all. 


As part of its housekeeping for each job, the monitor keeps track of: 
e Where the currently appropriate run-time system is 
e Where the user job image is 


e What the values were in the program counter register (PC), program status 
word (PSW), and other job-context information at the end of the last time 
slice 


Before the next time slice for the job, the monitor loads the APRs with the correct 
values for the job and loads the PC, PSW, and so forth, so execution continues 
where it left off. 


In any case, the high segment or run-time system takes up some multiple of 

4K words of virtual address space, due to the APR mapping (see the previous 
section). For example, the BASIC-PLUS run-time system, can take from 13 to 
16K words of physical memory, depending on options selected when the system is 
installed. Even though the physical memory required may be only 13K words, it 
still requires four APRs to map this range, leaving four APRs (or a maximum of 
16K words) for a user program. The monitor uses certain areas within the high 
segment and the low segment to get information from the job (defining what work 
the monitor is to do for it) and to pass information back to the job. 
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Figure 2—5 shows the job area in virtual addresses. RSTS/E uses the first 512. 
bytes to pass information between the monitor, the run-time system, and the 
user job image for certain types of monitor directives. The monitor uses the 
pseudovector region in high virtual memory to determine, for example, where 
control is to be passed when a job is initially entered. The run-time system loads 
this area with entry points and values to define itself to the monitor. 


Figure 2-5: Job Area in Virtual Memory 
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The following subsections give more detail on these areas: 


e If you are interested in using the general monitor directives Chapter 3 
describes, read the next section in this chapter, "Low-Segment Details: First 
512. Bytes of the Low Segment." 


e If you want to code your own run-time system or modify one of the existing 
ones and need to know about the pseudovector region, read the section in this 
chapter entitled "High-Segment Details: Pseudovectors." 


e If you are using only the directives Chapters 5 or Chapter 7 describe, the RSX 
and RT-11 run-time system directives set up the first 512. bytes of memory 
for you. 
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2.2.1 Low-Segment Details: First 512. Bytes of the Low Segment 


The monitor attaches special significance to the first 512. bytes of virtual 
address space in the low segment. The RSX Task Builder and RT-11 Linker 
automatically allocate this space. These programs always assign relocatable 
addresses beginning at location 1000 unless you request otherwise. If you want 
to use the general monitor directives Chapter 3 describes, your program must 
fill parts of this area with information for the monitor; the monitor passes 
information back in this area. 


Rather than use octal addresses, you can use the COMMON.MAC prefix file, 
which Chapter 3 describes ("Prefix File COMMON.MAC"), to assign mnemonic 
names to commonly used addresses and offsets. COMMON.MAC does not allocate 
space, but rather assigns mnemonic names to areas within the first 512. bytes 
of virtual address space. Use the mnemonics assigned with COMMON.MAC to 
make the code more readable and easier to maintain. 


Figure 2-6 shows the general regions in this area. Note that a run-time system 
may use some of the areas differently when it assumes control. For example, 
the RSX emulator uses the memory labeled default SP stack area as a table of 
logical units. The Task Builder automatically generates a user stack after the 
first 512. bytes of virtual address space. The section titled "First 512. Bytes of 
Low Segment for RSX" in Chapter 4 briefly describes how RSX uses the first 512. 
bytes. 


If you use the general RSTS/E directives, you should reference only the areas that 
are shown with mnemonics provided by COMMON.MAC. The mnemonics to the 
right in Figure 2-6 are assigned through COMMON.MAC. A general description 
of these mnemonics follows Figure 2-6. The general monitor calls in Chapter 3 
describe specific formats for the areas the calls use. 


Jobs do not have access to the job headers as part of the low segment. 
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Figure 2-6: First 512. Bytes of Low Segment 
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image or run-time system 


used by monitor for job 
context information to make job swappable 


used by monitor for 
hardware floating-point context information 
to make job swappable 


default SP stack area 


170 


400 KEY USRSP 


402 FIRQB 


442 XRB 
transfer request block 
460 CORCMN 
core common area 
| | 660 
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KEY (Keyword) 


The keyword defines the job’s status in the time-sharing environment; for exam- 
ple, the job’s privilege. Bits in the keyword can be set and cleared by the monitor 
or by the job (either the run-time system or the user job image). The job can 
manipulate some bits in the keyword with the SET and .CLEAR directives. 


The keyword is "refreshed" by the monitor at certain points; for example, when a 
run-time system is entered at P RUN, where the intent is to load and execute a 
program file in the user job image (.RUN directive). For a keyword refresh, the 
monitor clears bit 15 and bits 7-0 and sets the remaining bits to indicate the job’s 
current status. Only seven bits (8-14) are significant to the monitor. You can use 
the other bits in whatever manner you want. 


JFSPRI 
JFFPP 
JFPRIV 
JFSYS 
JFNOPR 
JFBIG 
JFLOCK 


15 14 #13 12 #11 #10 9Q 8 7 0 
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The following descriptions apply when the keyword status bit is set to one: 


JFLOCK 


JFBIG 


JENOPR 


JESYS 


JFPRIV 


JEFPP 


JFSPRI 


The job does not want to be swapped. You can change this bit with .SET and 
.CLEAR. When this bit is set, the only normal condition that causes the job 
to be swapped is when the job asks for a memory size expansion (see CORE 
directive) and there is not enough room to do the expansion where the job now 
is In memory. 

The job can exceed its private memory maximum (see .CORE directive). This 
bit is set if the job currently has EXQTA privilege, usually because the job is 
running a privileged program. JFBIG is an informational bit that the system 
updates whenever the EXQTA privilege is turned on or off. 


The job is not yet logged in. JEFNOPR is an informational bit that the monitor 
can alter when the job is logged in. 


The job is currently running with temporary privileges. The monitor sets 
JFSYS when a job with insufficient privileges needs to run a privileged 
program. Once the program is run, the job can regain temporary privilege by 
setting this bit and can drop privilege temporarily by clearing it. 


NOTE 


When a job exits from a privileged utility 
that can be executed by users with insuffi- 
cient privileges, the monitor clears this bit 
so another user cannot use the temporary 
privilege set up for the job. 


This bit is only for compatibilty with RSTS/E releases prior to V9.0. JFPRIV 
is set if the current job has all of the following privileges: HWCFG, SWCFG, 
SYSIO, RDMEM, and WWRITE. 


NOTE 


Any new software should not reference 
JFPRIV. 


The contents of the hardware floating-point unit (if any) should be part of 
the context of this job. That is, information in the floating-point registers 
should be saved and restored along with the rest of the user job image during 
swapping. Any program that uses the hardware floating-point unit should set 
this bit. It can be changed with the .SET and .CLEAR directives. 


The job is running with a special run priority: 1/2 level higher than normal. 
This bit can be changed with the .SET and .CLEAR directives. The monitor 
clears JFSPRI when the program exits. 


USRSP (User Space) 


COMMON.MAC assigns the value 400 to USRSP. The monitor automatically 
loads this value into the stack pointer register (SP) when a job is created. SP is 
also reset to this value under certain conditions, effectively establishing a default 
user stack area for the job beginning at word 376. The user stack area ends at 
location 170. Any attempt to push the stack past location 170 results in a stack 
overflow error that is handled by the run-time system (see the description of 
P.BAD later in this chapter). 
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You can change SP if you want. However, any attempt to reset SP to any location 
between 0 and 167 causes a stack overflow error. In addition, the monitor resets 
SP to 400 when a run-time system is entered with a .RUN, .CCL, or .RTS direc- 
tive, and when certain catastrophic errors occur, such as a fatal disk error while 
the user job image was being swapped. 


NOTE 


You need to be aware that the monitor resets SP at these times only if 
you are coding or modifying a run-time system. The system does not 
return control to a user program under these conditions, because the 
program cannot recover. 


FIRQB (File Request Block) 


The FIRQB is the main communication area between the monitor and the job for 
monitor directives that involve file or device operations such as open, close, and 
so forth. Either the run-time system or the user job image can use this area: 


e If you use the general monitor directives that Chapter 3 describes, your 
MACRO program must store values in the FIRQB before issuing some of the 
directives. 


e If you choose to use the directives in the RSX emulator or the RT-11 run-time 
system, the RSX or RT-11 emulation code intercepts the request, sets up the 
FIRQB and other relevant areas, then calls the monitor to handle the request. 


Figure 2—7 shows the general format of the FIRQB, with all mnemonics that 
COMMON.MAC assigns. In addition, the size of the FIRQB (32. bytes) has the 
mnemonic FQBSIZ. 


2-12 General RSTS/E Environment 


Figure 2-7: General FIRQB Format 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
FQFUN 3 CALFIP/.UUO subfne. job number * 2 | 2 FQJOB 
rasizm | MSBeffiosize | channelnumber"2 | 4 FOFIL 

FQERNO 
11 file name in RAD5O format | 10  FQNAM1 
(2 words) 
13 lie 
15 file type in RAD50 format (1 word) 14 FQEXT 
17 LSB of file size |} 16 FQSIZ 
21 buffer length | 20 FQBUFL/ 
3 FQNAM2 
25 status flags 24 FQFLAG 
FQPROT 27 | protection code =0, prot. code real | 26 FQPFLG 
31 device name (2 ASCII characters) | 30 FQDEV 
33 =0,unit number real 32 FQDEVN 
37 number of entries in directory lookup 36 FQNENT 


XRB (Transfer Request Block) 


The XRB is the main communication area between the monitor and the user for 
monitor directives handling file or device I/O. It is also the area in which the 
monitor stores information requested by straightforward information-request 
calls. As with the FIRQB, the general monitor directives (see Chapter 3) require 
that you store and retrieve information directly to and from the XRB. The RSX 
and RT—11 emulators handle additional directives, which they translate to calls 
using the XRB (see Chapters 5 and 7). Figure 2-8 shows the general format of 
the XRB, with all mnemonics that COMMON.MAC assigns. In addition, the size 
of the XRB (14. bytes) has the mnemonic XRBSIZ. 
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Figure 2-8: General XRB Format 


Mne— Octal Octal Mne- 
monic Offset Offset monic 


A buffer, as defined by XRLOC for its start and (KRLOC+XRLEN)-1 for its last 
byte, can be either an input buffer or an output buffer. RSTS/E uses input 
buffers to read data into user memory and output buffers to write data from user 
memory. These buffers must lie wholly within either the job-image (low segment), 
or the run-time system (high segment), or they must start in a window mapped to 
some library. Buffers within libraries must lie wholly within the library, but need 
not be wholly mapped. 


For input buffers, the value passed in XRB+XRBC must be zero. For output 

_ buffers, the value passed in XRB+XRBC is the number of bytes to be sent and 
cannot be zero if the value in XRB+XRLEN is nonzero. In addition, input buffers 
are subject to the following rules: 


e If the buffer is in the low segment, the address defined by the contents of 
XRB+XRLOC must be greater than 170 to avoid destroying the job-context 
data used in swapping the job. 


e Ifthe buffer is in the high segment, it must not fall within the pseudovector 
region. That is, it must not fall above the location P.OFF. In addition, the 
run-time system must currently be mapped read/write because the monitor 
is writing data to the buffer for the receive (see PF.RW bit description in 
P.FLAG word). | 


e Ifthe buffer is in a library window, the library must be installed as read/write 
and must be attached and mapped read/write. 


CORCMN (Core Common Area) 


The CORCMN is used as a common data exchange area when it is necessary 
to exchange lengthy data (such as strings) between the monitor and the job or 
between programs running under the same job number. 
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For example, the monitor uses CORCMN to pass to the job a string that is the 
full name of a command that has been recognized as a valid Concise Command 
Language (CCL) command. The RSTS/E CCL lets users type one-line commands 
to call utilities that might otherwise require several input lines from the terminal. 
For example: 


CCL Form 

$ PIP FILE1.=FILE2. 
$ 

Regular Form 


$ RUN SPIP 
*FILE1.=FILE2. 
KAT 


$ 


To centralize decoding, the monitor analyzes CCL commands by comparing them 
to those defined by the system manager (usually during system start-up). With 
the .CCL directive, a job can ask the monitor to analyze a string to see if it is an 
acceptable command. If it is, the monitor passes control to the run-time system 
associated with that CCL command and passes the command and any arguments 
to the job in the CORCMN area. 


The general format of the CORCMN area is: 


byte 1 of string number of bytes 
in string 


460 CORCMN 


byte 2 of string 


byte 3 of string 462 


(up to 127. bytes of data) 


USRPPN, USRPRT, USRLOG and the Extended Logical Area 


These bytes are set up using the .ULOG directive to store the assigned project- 
programmer number (USRPPN), default protection code (USRPRT), and assigned 
logical device names (USRLOG or the extended logical area of the job header), 
which the monitor then uses when an .FSS directive is executed. The .FSS 
directive causes the monitor to convert a file name string to the standard RSTS/E 
file specification format; that is, to the FIRQB format. 


The USRLOG byte is no longer used in RSTS/E V10.0. The information formerly 
passed in that byte is now passed in the extended logical area of the job header. 
The .FSS directive first processes the extended logical area of the job header. If 
there are no logicals there, it checks the old USRLOG area for logicals before 
returning an error. 


The .ULOG and .FSS directives also let you define and use some nonstandard 
area to contain these values (see Chapter 3). However, the .ULOG directive now 
sets up the extended logical area of the job header; the .FSS directive expects 
these values in the same relative locations. 


NOTE 


The only way you can manipulate the extended logical area of the job 
header is by using the the .ULOG directive. 
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2.2.2 High-Segment Details: Pseudovectors 


The monitor and the run-time system use the pseudovector region to communicate 
with each other. Figure 2—9 shows the general layout of this area. As with 

the low 512. bytes of virtual address space, the file COMMON.MAC assigns 
mnemonic names to locations in this area. These names are shown to the right 
in Figure 2-9. The following text describes each of these areas in detail. If you 
want to modify or code your own run-time system, the format and meaning of 
these areas is important. Otherwise, you might want to examine them to see how 
the run-time system and the monitor communicate. 


Figure 2-9: Format of Pseudovector Region of High Segment 


Addresses Mnemonics 


1177732 P.FLAG/ 
P.OFF 
177734 P.DEXT 
177736 
| 177740 P.MSIZ 
177742 P.FIS 
177744 
177746 
177750 P.NEW 
177752 P.RUN 
177754 P.BAD 
177756 P.BPT 
177760 P.1OT 
177762 P.EMT 


177764 P.TRAP 


4 


177766 P.FPP 
177770 P.CC 

177772 P.2CC 
(in K words) 177774 P.SIZE 


(reserved) 177776 


In general, the pseudovector region contains: 


e Values and flags that define the capabilities of the run-time system for the 
monitor. For example, one flag indicates whether the run-time system has a 
keyboard monitor. 
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e Addresses pointing to locations in the run-time system where the monitor is 
to pass control when certain conditions occur, These addresses fall into three 
categories: 


- Addresses for Synchronous Exceptions. Control passes to these locations 
when the job executes an instruction that causes a trap to the monitor. 
The monitor passes control to the run-time system along with the contents 
of the program counter (PC) and program status word (PSW). The term 
“synchronous is used in the sense that the trap occurs at the same time 
as (and is a direct result of) some instruction executed by the job. These 
traps may or may not indicate an error. For example (except for the 
PDP-11/23 PLUS or 11/24), if the job executes an instruction with an odd 
address, control passes to one of these trap addresses. If the job simply 
executes a BPT instruction, control passes to another of these addresses. 


— Addresses for Asynchronous Exceptions. Control passes to these locations 
as a result of some event, which can be either of the following: 


e External to the execution of the job (for example, the user types a 
Ctrl/C at the terminal) 


e Internal but asynchronous process (such as an error in the hardware 
floating-point processor, whose execution overlaps that of the PDP-—11 
CPU) 


When such conditions occur, control passes to the monitor, which passes 
control to the run-time system, along with the contents of the PC and 
PSW. If a floating-point trap occurred, the monitor also passes along the 
floating exception code (FEC) and floating exception address (FEA). For 
the asynchronous traps, the PC and PSW do not refer to the instruction 
that caused the trap, but to the instruction that was executing in the 
central processor when the trap occurred. 


— Entry Point Addresses. The monitor passes control to the run-time system 
at entry-point addresses when some major transition point is reached for 
the job. For example, when you type a RUN or CCL command at the 
terminal, the monitor passes control to an entry point in the appropriate 
run-time system, to load and execute the requested program. 


NOTE 


The term pseudovector arises from the relationship of some of these 
(one-word) trap addresses in the pseudovector region to the (two-word) 
vector addresses in kernel-mode memory set up to handle error traps 
and interrupts in the PDP—11. When the RSTS/E monitor receives 
control as a result of a trap to certain of these vector addresses, it 
passes control on to the run-time system at addresses specified in the 
pseudovector region. 


Normally, you code the contents of the pseudovector region as part of the run- 
time system file. However, the INSTALL/RUNTIME_SYSTEM command, used 
to define a file as an auxiliary run-time system, has qualifiers that cause the 
monitor to override certain portions of the pseudovector region in the file and use 
values assigned in the INSTALL command. For example, one bit in one word 

of the pseudovector region states whether the run-time system is read/write or 
read-only when it is loaded in memory. Normally, this would be read-only, but 
for debugging a run-time system with the Octal Debugging Tool (ODT), which 
allows you to change memory, the run-time system must be read/write. The 
/NOREAD_ONLY qualifier in the INSTALL command lets you tell the monitor 
that until further notice, this run-time system is read/write, regardless of what is 
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specified in the pseudovectors. The RSTS/E System Manager’s Guide describes 
the INSTALL/RUNTIME_SYSTEM command. 


2.2.2.1 Run-Time System Capability and Default Definitions 


The following mnemonics refer to values and flags that define run-time system 
capabilities for the monitor. 


P.OFF 


Use the POFF mnemonic to define the first word of the pseudovector region. It is 
currently set equivalent to 177732, the same as PFLAG. 


P.FLAG 


The monitor expects the PFLAG word to be set with flags that define the capabil- 
ities of the run-time system: 


PF.KB 
PF.1US 
PF.R 
PF.NE 
PF.RE 
_PF.CSZ 
PF.EMT 
15 14 13 12 1110 9 8 7 P 
Legs (erotic EMT code if PFLEMT=1) 
PF.EMT 


This bit is set to indicate that the run-time system wants to handle a call that 
would normally be handled by the monitor. To show how the bit works, it is 
necessary to first describe what normally happens when a monitor directive is 
translated and executed. 


All of the monitor directives that this manual describes are translated to emulator 
trap (EMT) instructions. The direct monitor calls are one-for-one translations; 
that is, one call is translated to one EMT (see Chapter 3). The code to process the 
call is in the monitor itself. 


The RSX and RT-11 emulator calls may be translated to more than one instruc- 
tion, but the code always contains an EMT. In addition, the direct monitor calls 
are translated to an EMT with a low byte that is an even number within the 
range 0 to 114 (octal). When such an instruction is executed, control transfers 
directly to the monitor, the call is processed, and control returns to the instruction 
following the EMT. 


An EMT instruction with an odd value in the range 1 to 113 in the low byte, 

or any value in the range 115 to 377, also transfer control to the monitor. The 
monitor examines the low byte, discovers that the EMT is not one of its own, and 
transfers control to the run-time system at the entry point defined by location 
P.EMT in the pseudovector region. 


Now the PF. EMT bit is set to one to indicate that the run-time system wants 
to process EMTs that are normally processed by the monitor, that is, with an 
even low byte in the range 0 to 114. When PF.EMT is set to one, all EMTs cause 
control to pass to the run-time system at the PEMT entry point, except those 
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immediately preceded by a special prefix EMT—an EMT whose low byte is equal 
to the low byte of PFLAG. 


Specifically, when PF.EMT equals one, the monitor handles all EMT instructions 
as follows: 


e Any EMT whose low byte is not equal to the low byte of PFLAG causes 
control to pass through the monitor (unprocessed except for examination), and 
back to the run-time system at the address contained in the PEMT word. 


e An EMT whose low byte is equal to the low byte of PFLAG causes control 
to pass to the monitor, which looks at the word following the EMT with the 
special code; that is, at the word in location (PC)+2. Action is taken according 
to the value of this word: 


! (PC)+2 = NO | Passcontrolto | 
an EMT instruction? (P.EMT) 


YES 


NO Pass control to 
( Low byte of (PC)+2 - : (P.EMT) 


even, 0 - 114? 


YES 


Execute second EMT 
@(PC)+2 as normal, 
return control to (PC)+4 


In other words, the run-time system does special processing for all EMTs, except 
those preceded by a special prefix EMT. The RT-11 run-time system uses this 
feature so it can emulate the RT—11 operating system’s directives properly. 


PF.CSZ 


For a user job image executed as a result of a .RUN directive, the monitor 
preallocates memory based on information provided by the run-time system 
under which the image is executing. When this bit is set, the monitor preallocates 
memory based on the size of the file referenced in the .RUN directive: 


space (in K words) = (filesize + 3)/4 


Filesize is the number of 512-byte blocks required for the file on disk. (The 
division by four is performed because there are four 512-byte blocks in 1K word. 
The addition of three rounds any fraction of the integer divide to the next whole 
integer.) 


When PF.CSZ is clear, the monitor preallocates memory for the image according 
to the value specified in the P MSIZ word of the pseudovector region. 
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PF.REM 


When the PF.REM bit is set, the monitor immediately removes the run-time 
system from memory when no job is using it. When this bit is clear, the monitor 
leaves the run-time system in memory until the space is actually needed by 
something else. 


PF.NER 


When this bit is set, the monitor does not log errors occurring within the run-time 
system to the system error log. 


PF.RW 


When this bit is set, the monitor maps the run-time system as read/write. (See 
the read/write feature of the Page Descriptor Register of an APR, in the section, 
"How RSTS/E Allocates Memory: Physical and Virtual Addressing.") This is a 
useful feature when debugging a run-time system. In normal operation, this bit 
should be clear, indicating that the run-time system is to be mapped read-only. 


PF.1US 


When the PF.1US bit is set, the monitor allows only one job to use the run-time 
system; that is, it is not handled as shareable code. 


PF.KBM 


When this bit is set, the monitor expects that the run-time system can function 
as a keyboard monitor. Note that the run-time system can function as a job 
keyboard monitor only when this bit is set. See the .RTS directive in Chapter 3 
for a discussion of job keyboard monitors. 


P.FLAG COMBINATIONS 


The PF.1US, PF.RW, PF.NER, and PF.REM bits are useful flags when you are 
debugging a run-time system: 


e PF.1US limits access to the run-time system to one user. 
¢ PERW is necessary if you want to use the ODT routine to change memory. 


e PF.NER keeps the run-time system from logging useless errors while debug- 
ging. 


e PE.REM ensures that the run-time system will be reloaded each time it is 
used. (Otherwise, an old copy might still remain in memory when you really 
wanted to debug a new copy.) 


P.DEXT 


You can set this word to three Radix—50 characters that the monitor uses as a 
default runnable file type. If a .RUN directive executes with no file type given, 
the monitor scans its list of installed run-time systems in the order they were 
installed (see Chapter 3). 


NOTE 


The order of installation shows up in the display that the SHOW 
RUNTIME_SYSTEM command produces. 
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The monitor first checks for .TSK files which are executed by the null run-time 
system. If such a file is found, it is set up for the .RUN. If no such file is found, 
the monitor searches for a file with the given file name and the next run-time 
system’s default runnable file type, and so forth. Note that the order in which 
the file types are chosen does not depend in any way on the run-time system 
executing the .RUN. 


P.MSIZ 


The P.MSIZ word gives the minimum allowable size for a user job image, in K 
words, for this run-time system. The monitor uses this value as a check when the 
job issues a .CORE directive to change the size of the user job image in memory 
(see Chapter 3). The value of PMSIZ must be an integer between 1 and the value 
in P.SIZE, inclusive. 


P.SIZE 


The P.SIZE word contains the maximum size, in K words, that a user job image 
can be for this run-time system. The monitor uses this value as a check when a 
job issues a .CORE directive to change the size of the user job image in memory. 
P.SIZE must be an integer between 1. and 32., inclusive. The effective upper 
limit is 32. minus the size of the run-time system, rounded up to a multiple of 
four. (Remember that the APR mapping requires that space for the run-time 
system be allocated in units of 4K words.) Thus, a run-time system that required 
5K words could set an upper limit here of 24. (32.-8.). However, it could set 
P.SIZE to some smaller value. 


2.2.2.2 Synchronous Exception Handler Addresses 


These mnemonics refer to locations in the run-time system where control is to 
pass for synchronous exceptions. 


P.FIS 


The monitor interprets the P.FIS word as the trap address for the hardware 
floating-point instruction set available on the PDP—11/35 and 40. Whenever 
an instruction from this set causing a trap to the kernel mode vector at 244 
is executed, the monitor passes control to the run-time system at the location 
specified by the contents of the P.FIS word. 


This exception pushes two words onto the user’s SP stack: the contents of the PC 
and PS registers at the time of the exception. For example: 


SP—. (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


Whatever action the run-time system wants to take for this exception should be 
done at the location specified by the contents of P.FIS. A return from interrupt 
(RTI) instruction returns control to the point where it was when the exception 
occurred. 


P.BAD — Synchronous Exceptions 


The monitor passes control to the run-time system at the location specified by the 
contents of P BAD when any of the following synchronous exceptions occur: 


¢ Memory management unit exception (trapped to kernel mode vector at 250). 


e The job tries to execute a reserved instruction (trapped to kernel mode vector 
at 10). 
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e The job issues an instruction with an odd address (trapped to kernel mode 
vector at 4). 


This exception pushes two words onto the user’s SP stack: the contents of the PC 
and PS registers at the time of the exception. For example: 


SP— (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The monitor returns an error code in the first byte of the FIRQB so the run-time 
system can determine which error occurred. The error codes are: 


B.4 Odd address 
B.10 Reserved instruction 
B.250 Memory management unit exception 


The run-time system is responsible for processing these errors in whatever 
manner it sees fit. In general, most run-time systems provided with RSTS/E 
systems report the error, using the UU.ERR subfunction of the .UUO directive 
and perhaps print the PC value from the top of the stack. You can use an RTI 
instruction to return control to the point where it left off when the exception 
occurred. Note that some asynchronous exceptions also use this address. 


P.BPT 


The P.BPT word contains the exception address for a BPT instruction and for 
T-bit exceptions. When the job issues a BPT instruction or a T-bit exception 
occurs (to the kernel mode vector at 14), the monitor passes control to the run- 
time system for the job at the address specified by the contents of this word. 


This exception pushes two words onto the user’s SP stack: the contents of the PC 
and PS registers. For example: 


SP— (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system processes these exceptions in any fashion it sees fit at the 
location specified by the contents of PBPT. The RTI or RTT instructions can be 
used to return control to the user’s program at the point where it was when the 
exception occurred. 


P.IOT 


The PIOT word contains the exception address for an IOT instruction. Whenever 
the job issues an IOT instruction (trapped to kernel mode vector at 20), the 
monitor passes control on to the run-time system at the address specified by the 
contents of this word. 


This exception pushes two words onto the user’s SP stack: the contents of the PC 
and PS registers at the time of the exception. For example: 


SP—> (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system can process the exception in any fashion it sees fit. You 
can use an RTT instruction to return control to the point where it was when the 
exception occurred. 
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P.EMT 


This word contains the location to which control is transferred for nonmonitor 
EMT instructions; that is, for EMT instructions whose low byte is odd within the 
range 1 to 113 or any value in the range 115 to 377. If the PE EMT hit is set in 
the PFLAG word in the pseudovector region, control is transferred here for all 
EMT instructions except those preceded by the special prefix EMT, as described 
previously. 


The exception pushes two words onto the user’s SP stack: the contents of the PC 
and PS registers at the time of the exception. For example: 


SP— (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system is responsible for processing the EMT as it sees fit. You 
can use the RTI instruction to return control to the point where it was when the 
exception occurred. 


NOTE 
All EMT instructions are reserved for use by Digital. 


P.TRAP 


This is the location to which control is transferred for all TRAP instructions 
(operation codes 104400 through 104777, inclusive). Whenever the job executes 
such an instruction (trapped to kernel mode vector 34), the monitor passes control 
to the run-time system at the location specified by the contents of this word. 


This exception pushes two words onto the user’s SP stack: the contents of the PC 
and PS registers at the time of the exception. For example: 


SP— (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system is responsible for processing the exception as it sees fit. You 
can use an RII instruction to return control to the point where it was when the 
exception occurred. 


2.2.2.3 Asynchronous Exception Handler Addresses 


These mnemonics refer to locations within the run-time system where control is 
to pass for asynchronous exceptions. 


P.FPP 


This location is the exception address for the hardware floating-point processor 
(FPP) for the PDP-11/34A, 44, 45, 50, 53, 55, 60, 70, 73, 83, 84, 93, and 94 
asynchronous unit or the KEF11-AA or FPF-11 for the PDP—11/23-PLUS and 24. 
Whenever the unit takes an exception trap (to kernel mode vector at 244), the 
monitor passes control to the run-time system at the location specified by the 
contents of this word. The Floating-point Exception Code (FEC) and Floating- 
point Error Address (FEA) of this unit are not otherwise accessible. 
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Therefore, the monitor pushes these two values onto the user’s SP stack, in 
addition to the contents of the PC and PS registers at the time of the interrupt. 
For example: 


SP— FEC 
FEA 
(PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system can process the exception as appropriate, clean the stack 
(remove the FEC and FEA), and issue an RTI instruction to return control to the 
user’s program at the point where it was when the exception occurred. 


P.CC 


This is the location to which control passes when a Ctrl/C is entered at any termi- 
nal on any channel that this job accepts. The monitor stops further programmed 
output for the job (Ctrl/O effect) and cancels any pending character output. 


The user’s SP stack is modified at entry. For example: 


SP—. (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system can process the Ctrl/C as you want. All run-time systems 
supplied with a RSTS/E system abort the job, unless the user job image has 
indicated that it wants to handle Ctrl/C traps itself (see the SCCA$S and the 
SETCC directives). 


P.2CC 


This is the exception address taken when the user enters a second Ctrl/C before 
the run-time system has been able to respond to the first Ctrl/C. (That is, the 
monitor has received two Ctrl/Cs before it has been able to pass control to the 
run-time system at the location specified by the contents of P.CC in the time- 
sharing environment.) As with one Ctrl/C, when the P.2CC point is entered, 
further programmed output is canceled (Ctrl/O effect), and any pending character 
output is canceled. Two words are pushed onto the user’s SP stack. For example: 


SP—. (PC) at the time of the exception 
(PS) at the time of the exception 
word to which SP pointed before the exception 


The run-time system can process the condition as you want (BASIC-PLUS exits 
immediately, returning control to the PNEW entry point in the default keyboard 
monitor). An RTI instruction would return control to the point where the program 
left off, but this annoys the user who entered the two Ctrl/Cs expecting to get out. 


P.BAD — Asynchronous Exceptions 


The monitor passes control to the location specified by P.BAD whenever any of 
the following asynchronous errors occur: 


e The user’s SP stack overflows. 


e A fatal disk error occurs when the job is swapped. The original contents of 
the user job image are lost. 


e A memory parity fault occurs in the user job image. The original contents of 
the user job image are lost. 
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e A fatal disk error occurs when a run-time system or resident library is loaded. 
Control passes to P.BAD in the default keyboard monitor when the load error 
occurs for a run-time system. 


None of these errors are recoverable. An error is returned in the first byte of the 
FIRQB to indicate which error occurred, KEY is refreshed, and the contents of the 
general registers (RO through R5) are random. SP is reset to the value USRSP. 


In general, most run-time systems provided with RSTS/E systems report the er- 
ror, using the UU.ERR subfunction of the .UUO directive, and also the ??Program 
lost-sorry message (UU.ERR call with FUCORE value). Then, the run-time 
systems exit to the job keyboard monitor, using RTS. The ??Program lost-sorry 
message prints to warn you that the program is no longer in memory and you 
user logical values may have been lost. 


The error codes that RSTS/E returns in the first byte of the FIRQB are: 


B.STAK The user’s SP stack overflowed 

B.SWAP Fatal disk error on swap 

B.PRTY Memory parity fault 

NRRTS Fatal disk error on run-time system or resident library load 


Control is also transferred to PBAD for some synchronous exceptions. 


2.2.2.4 Entry Points 


These mnemonics refer to locations within the run-time system where control is 
to pass at certain transition points for the job. 


P.NEW 


The monitor passes control to this entry point under the assumption that new 
user or next request processing is to be done. Compare this to the PRUN entry 
point, where a specific program is to be run under this run-time system. PNEW 
is commonly used as the entry point to switch back to a job’s keyboard monitor. 
For example, the .EXIT directive passes control to this entry point in the system 
default keyboard monitor. You can use the .RTS directive to pass control to 
P.NEW in a job’s keyboard monitor or a specifically named run-time system. Note 
that a job can establish its own job keyboard monitor, which is different from the 
default keyboard monitor (see the section on .RTS in Chapter 3). 


By examining KEY and the XRB, the run-time system can determine how and 
by whom it was entered at PNEW, if this is significant. (Run-time systems that 
do not have keyboard monitors would probably want to exit (using .EXIT) to the 
default keyboard monitor at PNEW.) 


The three conditions under which control passes to the PNEW entry are: 


e Brand new job on the system—lIn this case, JFNOPR (bit 12 in KEY) is set 
(the job is not yet logged in), and the words at location XRB+2 and XRB+4 are 
zero (the monitor requested the entry, not a run-time system). This indicates 
that the monitor has passed control to this location, having received input 
over channel zero in a logged-out state (occurs only for the default keyboard 
monitor). 


The run-time system should run some predetermined program to read (.READ 
directive) the input line that the monitor has buffered. For example, DCL 
executes SY:[1,2]LOGIN.* (the LOGIN utility) in this case. 
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° Switch to this run-time system when job logged out—In this case, JFNOPR 
(bit 12 in KEY) is set, and the name of the calling run-time system is given 
as two RAD50 words in locations XRB+2 and XRB+4. The calling run-time 
system is the run-time system under whose control the directive was issued 
that caused the switch. 


For this case, the run-time system should issue a logged-out prompt message. 
For example, the BASIC-PLUS run-time system prints "Bye" and returns 
control to the monitor. (Normally, control does not pass to the run-time 
system in this case. If LOGIN does not recognize the line that it read (as in 
previous case), it kills itself, destroying the job and returning control to the 
monitor.) 


° Switch to this run-time system when job logged in—In this case, JFNOPR (bit 
12 in KEY) will be clear. The name of the calling run-time system is given as 
two words of RAD5O in locations XRB+2 and XRB+4 or is zero if this job was 
just created by UU.JOB (see Chapter 3). 


For this situation, the run-time system should issue its logged-in prompt and 
attempt to read the next command from the terminal open on channel zero. 
BASIC-PLUS prints "Ready", DCL prints "$", RSX prints ">", and RT-11 
prints ".". Then, all wait for further input. 


Keyboard monitors should read channel zero (the job’s terminal) using the key- 
board monitor wait feature of .READ. The monitor will kill jobs that execute this 
read in a logged-out state; otherwise, it is an infinite-wait read. 


The monitor usually does some housekeeping for the job at the time the P NEW 
entry point is entered. Specifically, the word at location FIRQB+FQJOB is always 
set to two times the job number assigned by the monitor when the job was 
created, and KEY is refreshed with current information about the job. Third- 
party privilege checking is turned off if it was on (see UU.3PP). Furthermore, SP 
is reset to 400 (see USRSP description), all the general registers (RO through R5) 
contain zero, and all I/O channels are closed. 


On exit from privileged programs, some additional clean-up is done: 
e Temporary privileges are dropped 
e User memory is cleared (upwards from location 1000) 


e User job image size is reset to the value in PMSIZ 


NOTE 


This housekeeping is not done if a specific request is made to pass con- 
trol to a run-time system without changing the job-context information 
(see the .RTS directive). 
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The following information exists in the XRB at the time the P. NEW entry point is 
entered: 


XRB on P.NEW Entry 


Octal Octal Mne- 
Offset Offset monic 
1 1 for switch without housekeeping; else 0 0 XRLEN 
3 2 XRBC 
name of the calling run-time system 
5 (2 words in RAD50 format) 4 XRLOC 
7 -1 if calling RTS = new RTS; else 0 6 XRCI 
11 10 XRBLK 
whatever values were here | 
13 when the switch was made 12 XRTIME 
15 14 XRMOD 
XRB+0 This word contains a value of one, if control was transferred by an .RTS direc- 


tive using the switch without changing the job-context option (see Chapter 3). 


XRB+2 The two words beginning here contain the name of the calling run-time 
system, in RAD50 format. If control was transferred here directly by the 
monitor, these two words contain zero. 

XRB+6 This word contains minus one if the calling run-time system is the same 
as the one that now has control. This word is zero otherwise; that is, if the 
calling run-time system is not the same as the called run-time system. 

XRB+10 The contents of the next three words will be the same as they were when 
the switch occurred. That is, data can be passed from run-time system to 
run-time system here. If control has been transferred to RP NEW directly by 
the monitor, these three words are zero. 


P.RUN 


The monitor passes control to the P.RUN entry point when an executable program 
is to be run for a job under control of this run-time system. This can occur as the 
result of either a .RUN or a .CHAIN directive (in which a job has directly asked 
for a file to be run) or a .CCL directive (in which a job has asked the monitor 

to check a string to see if it is a valid CCL command, and if so, execute the 
appropriate file). 


The monitor opens the file to be run (a disk file) on channel 15. However, the file 
has not been read; it is up to the run-time system to load and execute the file. 
The run-time system should also reset all I/O channels except 15, in case they are 
open. 


The monitor performs the same housekeeping operations as with P NEW (reset 
the stack, and so on). In addition, if the program to be run is a privileged 
program, and the caller does not have all of the program’s privileges, the monitor 
sets the JFSYS bit in KEY, saves the current privileges, and adds the program’s 
privileges to the current privileges. 
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The monitor passes data to the run-time system in the XRB, FIRQB, and KEY 
areas of the user job image (low segment). 


Octal 
Offset 


XRB on P.RUN Entry 


Octal Mne- 
Offset monic 


flag bits describing entry conditions XRLEN 


XRBC 


name of run-time system which issued 


the call to this one XRLOC 


XRCI 


XRBLK 


same value as when the caller XRTIME 


issued the .RUN or .CCL 


XRMOD 


XRB+0 This word contains flag bits that describe the entry conditions. (The 
STATUS variable in BASIC-PLUS returns these values.) 


Bit 
0-7 


8-12 
13 


14 


15 


Meaning 


If the value of these bits is zero, then no special size for this 
program run is called for. If the value is greater than zero, it 
indicates the size, in K words, that the program should be run 
at. If the value is less than zero, the absolute value indicates 
an increment, in K words, to the size that the program would 
normally run at. 


Reserved for future use. 


When set, indicates that the caller issued a directive with a 
/SIZE switch; that is, the file is to be run at a specific size. The 
size is given in bits 0-7. It is up to the run-time system to set 
the size as indicated (see the .CORE directive). 


When set, indicates the caller issued a .CCL directive with a 
/DETACH switch, with the intent that this run-time system 
executes the file in detached mode. It is up to the run-time 
system to take action on this flag. You can detach a job by 
using the UU.DET subfunction of the .UUO directive; see 
Chapter 3. 


When set, indicates the entry was made as the result of a .CCL 
directive. When clear, indicates the entry was made as the 
result of a .RUN or a .CHAIN directive. 


XRB+2 These two words contain the name of the run-time system under which 
the .RUN, .CHAIN, or .CCL directive to this run-time system was issued, 
in RAD50 format. 


XRB+6 The contents of this word are random. 


XRB+10 The three words beginning here contain the same information that they 
held when the job issued the .RUN, .CHAIN, or .CCL directive. 
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FIRQB on P.RUN Entry 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
. . 
) 
11 file name in RAD50 format 10 FQNAM1 
(2 words) 
13 | 12 
31 | device name (2 ASCII characters) | 30 FQDEV 
FIRQB+FQJOB The job number (assigned by the monitor when this job was 
created) times two. 
FIRQB+FQPPN The project-programmer number for the file that is to be run. 
FIRQB+FQNAM1 The name of the file that is to be run, as two words in RAD50 
format. 
FIRQB+FQEXT The type of the file that is to be run, as one word in RAD50 
format. 
FIRQB+FQSIZ The file size, in 512-byte blocks. 
FIRQB+FQBUFL The recommended size, in bytes, for the buffer size in a .READ 
directive for this file. 
FIRQB+FQFLAG Flag bits defining the device. They are set to indicate that this is 


a disk file. (See the FQFLAG description in the open function of 
the CALFIP directive.) 


FIRQB+FQPFLG The file cluster size, modulo 256. (That is, a file cluster size of 
256 is indicated by a zero byte here.) This byte is the same as 
the FQCLUS value supplied in the open functions of the CALFIP 


directive, except that it is returned in a byte instead of a word. 


FIRQB+FQPROT The protection code of the file. 
FIRQB+FQDEV The device name of the disk device, as two ASCII characters. 
FIRQB+FQDEVN The unit number of the disk device. 
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FIRQB+FQDEVN+1 The low-order two bits of this byte are set to indicate whether or 
not the device is part of the public structure: 


Bit 0 = 0 The device is in the public structure. 
=] The device is a private disk. 
Bit 1 = 0 A specific device was not specified in the open 
function. 
= 1 A specific device was specified in the open func- 
tion. 
FIRQB+FQCLUS The file identification index of this file. This word is significant 


in that you can use it in place of the file name in subsequent 
opens of the file on disk. You can open the file with the OPNFQ 
subfunction of CALFIP, using: 


e An explicit PPN in FIRQB+FQPPN 

e <A zero word in FIRQB+FQNAM1 

e An explicit device name in FQDEV and FQDEVN 
e The file identification index in FIRQB+FQNAM1+2 


| FIRQB+FQNENT Parameter word from the caller. The .RUN or .CHAIN directive, 
which causes entry at PRUN in a run-time system, allows the 
caller to specify a parameter word to be passed to the run-time 
system. Bit 15 of this word may or may not be the same as 
the caller passed, however. If the .RUN or .CHAIN directive 
was issued from a privileged program with temporary privileges 
enabled, bit 15 is passed by the caller. Otherwise, bit 15 is cleared. 


For .CCL entries, bit 15 is set by the monitor. If the CCL defini- 
tion for the CCL being executed has the /PRIVILEGED qualifier 
included in it, the bit 15 is set; otherwise, it is cleared. 
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Chapter 3 


General Monitor Directives 


This chapter describes the general directives to the RSTS/E monitor. These 
directives are available to the MACRO programmer under both the RSX and 
RT-11 run-time systems. They are Emulator Trap (EMT) instructions that are 
processed directly by the monitor. A run-time system does not examine or process 
these general directives. 


3.1 Summary of General Monitor Directives 


Table 3-1 summarizes the general monitor directives. Detailed descriptions are 
given in the sections that follow this introductory material. The descriptions are 
arranged alphabetically by mnemonic name. 


Some directives, which cause a change in run-time system or change in job size, 
should not be executed by a program (user job image) running under the RT-11 
run-time system, or unpredictable results may occur. These directives are marked 
with a dagger (+) or double dagger (t) in Table 3-1. (Note, however, that these 
are not restrictions for assembling using MACRO—the assembler for the RT-11 
run-time system. If you are coding a run-time system, you use these directives 
and assemble under either MACRO or MAC.) 


Table 3-1: Summary of General Monitor Calls 


EMT 
Code 
Name (Octal) Description 
CALFIP 0 Call the File Processor portion of the RSTS/E monitor. Includes 
"housekeeping" functions for file/device I/O such as OPEN, 
CLOSE. 
“READ 2 Read from a previously opened file or device. 
WRITE 4. Write to a previously opened file or device. 
.CORET 6 Change memory size allocated for user job image. 
SLEEP 10 Sleep job for n seconds. 
.PEEK 12 Peek at the monitor’s memory. 
SPEC 14 Special function. 
.TTAPE 16 Enter tape mode. 


+These directives should not be used by a program running under control of the RT-11 run-time 
system. — 


(continued on next page) 


General Monitor Directives 3-1 


Table 3—1 (Cont.): 


Name 


.TTECH 
-TTNCH 
.TTDDT 
-TTRST 
.TIME 
.POSTN 
-DATE 
SET 
STAT 
-RONT 
NAME 
EXIT 
RTST 
.ERLOG 
.LOGS 
.CLEAR 
.MESAG 
.CCLt 
SST 
.UUO 


-CHAINE 
-PLAS 
.ULOG 


-READA _ 


-WRITA 
ASTX 
-CMDLN 
AST 


EMT 
Code 
(Octal) 


20 
22 
24 
26 
30 
32 
34 
36 


102 
104 
106 
112 
114 


Summary of General Monitor Calls 


Description 


Enable echo on a channel. 

Disable echo on a channel. 

Enter ODT submode on a channel. 

Cancel Ctrl/O effect. 

Get timing information. 

Get device’s horizontal position. 

Get current date. 

Set keyword bits. 

Get statistics for job. 

Run new program (user job image). 

Install a new program name. 

Exit to default keyboard monitor. 

Switch to new run-time system. 

Log an error from run-time system. 

Check for logical devices. 

Clear keyword bits. 

Message send/receive. 

Check string to see if Concise Command Language (CCL). 
Scan a string for valid RSTS/E file specifications. 


Execute monitor FIP call (access to BASIC-PLUS SYS calls to 
FIP). 


Execute user job image under same run-time system. 
Access a shared library. 

Assign/reassign/deassign device or user logical. 
Asynchronous read. | 
Asynchronous write. 

AST exit. 

Read/write command line buffer. 

AST enable/disable. 


+These directives should not be used by a program running under control of the RT-11 run-time 


system. 


tThis directive should not be used by a program running under control of either the RT-11 run-time 
system or the RSX emulator. 


Prefix File COMMON.MAC 


The monitor directives that this chapter describes require that you pass param- 
eters to the monitor in the FIRQB and XRB; values are also returned to your 
program in these areas. The file COMMON.MAC, provided with all RSTS/E kits, 
relates mnemonics to often-used addresses, offset values, and function codes, 
eliminating the need for octal coding and addressing. These mnemonics are 
used in the directive descriptions that follow; Digital recommends their use for 
readable, maintainable code. 
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3.1.1.1 How to Assemble with COMMON.MAC 


COMMON.MAC is a prefix file; it is assembled with your other MACRO 
source files under either the RSX or RT-11 run-time systems. For example, 
under the RT-11 run-time system, the following sequence would assemble the 
files COMMON.MAC, SRC1.MAC, and SRC2.MAC into the object module file 
OBJ.OBJ with an assembly listing file OBJ.LST: 


RUN SMACRO 
*OBJ, OBJ=COMMON, SRC1, SRC2 


Similarly, under the RSX run-time system, this sequence would assemble the 
files COMMON.MAC, SRC1.MAC, and SRC2.MAC into the object module file 
OBJ.OBJ with an assembly listing file OBJ.LST: 


RUN SMAC 
MAC>OBJ, OBJ=COMMON, SRC1, SRC2 


You can also use the INCLUDE assembly directive to include COMMON.MAC. 
Use the following line as the first line of the source file: 


» INCLUDE /COMMON/ 


3.1.1.2 Macros Provided in COMMON.MAC 


In addition to providing mnemonics, the COMMON.MAC file contains macros 
that can be used in programs assembled under either the RSX or RT-11 run-time 
systems, as long as COMMON.MAC is assembled with the source, as described 
previously. These macros are: 


TITLE name,desc,nn,date,editors 


The TITLE macro sets a title (. TITLE) from the name and description (desc) 
parameters and builds an identification (IDENT) from the specified number 
nn. The IDENT has the form xx.xnn, where xx.x is the current RSTS/E ver- 
sion number (09.0 for V9.0), and nn is the edit level you specify. Descriptive 
information is placed in the table of contents as follows: 


EDIT: DATE: BY: 
nn date editors 
ORG sectionl, offset] 


ORG defines the origin address of a program section. The first occurrence of 
an ORG with a given section name causes all instructions requiring memory 
space following the ORG to be assigned consecutive relocatable addresses 
starting with zero or, if an offset is given, with the octal address given. Later 
occurrences of an ORG with the same section name causes resumption of 
addressing wherever it left off before, because of an intervening ORG. 


The ORG macro also defines a symbol with the same name as the section at 
the first relative location within the section. Every invocation of ORG also 
defines (or redefines) the section to be returned to by the macro UNORG. 


DEFORG section 


The DEFORG macro is the same as the ORG macro except that the symbol at 
relative 0 (the section name) is declared as a global symbol. By convention, 
the module that defines the section (rather than just uses it) issues the 
DEFORG macro. 
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TMPORG sectionl, offset] 


TMPORG is the same as ORG except that it does not define (or redefine) the 
section to be reentered by the UNORG macro. In this way, the module can 
temporarily enter a new section and then return to the main section using 
UNORG without having to know the main section name. 


UNORG 


The UNORG macro will reenter the section most recently declared in an ORG 
or DEFORG macro. 


INCLUDE namel[,name?2.,...] 


The INCLUDE macro indicates that the module issuing the INCLUDE 
requires the named modules (namel, ...). The name(s) should be declared 
with DEFORG(s) in the required modules. 


INCLUDE declares the listed section names as global symbols and issues 
the macro directive SBTTL with the heading "INCLUDE FROM LIBRARY 
‘name to be inserted in the assembly listing table of contents. INCLUDE 
documents the named sections as required by this section. 


-DSECT [start][,cref] 


The .DSECT macro starts a dummy program section (with the MACRO 
directive .ASECT) at relocatable address 0 or at the address given by the 
optional argument start. If the cross-reference (cref) parameter is given 
(nonblank), the program section is included in the cross-reference listing, if 
you request one for the assembly. 


The .DSECT macro is used in the file COMMON.MAC to define the system 
parameters and offsets. 


For example, coding of this form is used in COMMON.MAC to assign the 
proper values to the mnemonics in the pseudo-vector region: 


.DSECT 177776, NOCREF 
. BLKW -1 
P.SIZE: . BLKW -1 
P.2CC: . BLKW -1 
P.CcC: . BLKW -1 


NOTE 


A .DSECT is used at the end of the file COMMON.MAC, This 
means that you must explicitly start your MACRO program with 
an ORG macro or .PSECT directive to begin your program at 
relocatable address 0. Otherwise, your code will be regarded as a 
continuation of the .DSECT, and the program will not assemble 
properly. 
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-BSECT [HIGHI][,cref] 


The .BSECT macro is like the .DSECT macro except that the default starting 
address is 1 instead of 0. If the argument HIGH is used, the starting address 
is 400 (octal). This starting address lets you use .BSECT to generate bit 
values. The .BSECT macro is used in COMMON.MAC to define mnemonics 
for bit locations. For example, the following coding assigns the mnemonics to 
the bit locations in the keyword (KEY; see Chapter 2). Note that the period (.) 
after .BLKB is required. 


~-BSECT HIGH, NOCREF 
JFSPRI1: - BLKB 


JFPP : - BLKB 


-EQUATE symbol,value 


EQUATE defines the given symbol to have the supplied value (which may be 
an expression) by using the equivalent of: 


-DSECT value 


-symbol: 
UNORG 


-BLKW0 [quantity][,value] © 


The .BLKW0O macro is similar to the MACRO directive .BLKW, which reserves 
a specified number of words of storage space. The quantity can be any 
expression, the default is one. While .BLKW just reserves space, .BLKW0 fills 
the space with the value you specify; the default is zero. 

-BLKBO [quantity][,value] 


The .BLKBO macro is similar to the MACRO directive .BLKB, which reserves 
a specified number of bytes of storage space. The quantity can be any expres- 
sion, the default is one. ._BLKBO fills the space with the value you specify; the 
default is zero. 


GLOBAL <namel[,name?2.,...]> 
GLOBAL declares the name symbols as external global symbols. 


RETURN [register] 
The RETURN macro generates an RTS PC by default but can generate any 
other RTS instruction if you specify an explicit register. 

JMPX label 
JMPX is just like the JMP instruction but will also declare the label to be an 
external global (that is, jump external). 

CALL subroutine[,register[,argument list]] 


You can use CALL instead of JSR PC to call subroutines. If an explicit 
register is specified, then the call is JSR using that register. If an argument 
list is specified, it generates a list of .WORD arguments in line with the 
subroutine call. 
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CALLR subroutine 


CALLR is equivalent to a CALL to a subroutine immediately followed by a 
RETURN. CALLR generates a JMP instruction. 


CALLX subroutine 


CALLX is just like CALL, but it also declares the subroutine name as an 
external global symbol. 


CALLRX subroutine 


CALLRX is just like CALLR except that the subroutine name is declared as 
an external global symbol. 


3.1.2 Error Mnemonics: Symbol Table File ERR.STB 


When the monitor processes the directives that this chapter describes, any errors 
that it detects are passed back to the job in the first byte of the FIRQB as a 
binary value. The ERR.STB file, provided with all RSTS/E kits, relates mnemonic 
values to these binary codes, so you do not have to analyze and process errors 

in octal. The descriptions in this chapter all refer to the mnemonics provided by 
ERR.STB. See Appendix A for a list of all possible errors. 


The symbols are automatically resolved at link time if you include ERR.STB with 
the files you link with either TKB (the Task Builder for the RSX run-time system) 
or LINK (the linker for the RT-11 run-time system). For example, under the RSX 
run-time system, the following code links ERR.STB and MAIN.OBJ to produce 
the executable file IMG1.TSK, a memory allocation file MP1.MAP, and a symbol 
definition file SF1.STB: 


RUN STKB 
TKB>IMG1, MP1, SF1=ERR.STB, MAIN 


Similarly, under the RT-11 run-time system, the following sequence links 
ERR.STB and MAIN.OBJ to produce the executable file IMG1.SAV, a memory 
allocation file MP1.MAP, and a symbol definition file SF1.STB: 


RUN SLINK 
*IMG1,MP1,SF1=ERR.STB, MAIN 


3.1.3 Programming Hints 
Preset the FIRQB and XRB to Zero 


The monitor directives in this chapter pass information to the monitor in the 
FIRQB and XRB areas of the low 512. bytes of memory. It is usually a good 
idea to clear the entire FIRQB and XRB before issuing a call, to ensure that no 
extraneous information (for example, from data returned on a previous call) has 
been left in the areas that could affect how the call executes. 


In some cases, however, you may want to leave the FIRQB and XRB alone. The 
.FSS call, for example, scans a string and, if it is a valid file specification, returns 
to the FIRQB the information needed to open the file with the CALFIP call. You 
do not want to clear the FIRQB before opening the file with CALFIP. 


NOTE 


To ensure compatibility with future releases of RSTS/E, you should 
always set to zero any fields in the FIRQB and XRB diagrams that are 
shaded or are documented as reserved or not used. 
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The following example contains three routines that clear the FIRQB and XRB. 


CLRFQX clears both the FIRQB and XRB. 
CLRFQB clears the FIRQB. 
CLRXRB clears the XRB. 


The values FQBSIZ and XRBSIZ used in these routines are defined in 
COMMON.MAC. 


-ENABL LSB 


CLRFQX: : PUSH <RO, R1> ;Save RO,RI1 
MOV #F ITROB, RO ;Point to FIRQB. 
MOV #<<FQBSIZ+XRBSIZ>/2>,R1 ;Compute how many words 
BR 108 sto clear. 
CLRFQB: : PUSH <RO, R1> ;Save RO,RI1 
MOV #F IROB, RO ;Point to FIRQB. 
MOV #<FOQBSIZ/2>,R1 ;Compute how many words 
BR 10S ;to clear. 
CLRXRB: : PUSH <RO, R1> ;Save RO,RI1 
MOV #XRB, RO ;Point to XRB 
MOV #<XRBSIZ/2>,R1 ;Compute how many words 
esto clear. 
10S: CLR (RO) + ;zZero it out ... 
SOB R1,108S 7’til all done 
POP <R1,RO> ;Restore RO,RI1. 
RETURN 
-DSABL LSB 


Data Returned to FIRQB and XRB 


If a call completes without error, the monitor sets byte 0 of the FIRQB to zero. If 
an error occurs on a call, the monitor sets byte 0 of the FIRQB to an error code. 
Likewise, the monitor always sets the byte at FIRQB+2 to the current job number 
times two when a call completes. 


In some circumstances, it may be useful to know what happens to the passed- 
data when a call completes. For instance, is the file name still there? Bytes not 
specified as containing returned-data are undefined. Do not rely on these values 
when coding your programs because Digital reserves the right to change the 
values returned in these bytes at any time. In addition, if an error occurs, the 
data returned may or may not have replaced the data passed. It depends on how 
far processing for the call got before the error occurred. 


Channel Numbers for 1/O 


Directives that handle I/O use a channel number to refer to a device. In device 
or file opens, a channel number is related to a specific device defined in the call. 
Directives that transfer data (.READ, .WRITE, .READA, .WRITA) can then refer 
to a channel number rather than define a device or file. 


Valid channel numbers range from 0 through 17. Channel 0 is the job’s terminal; 
for example, a .WRITE to channel 0 writes to the terminal which is running the 
job. Channel 0 is always open. Similarly, the monitor opens a file to be run on 
channel 17 when control transfers to the P RUN entry point in a run-time system. 
Thus, user jobs may define and use channels 1 to 16. 
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Directives That Do I/O 


The CALFIP subfunctions OPNFQ, CREFQ, CRBFQ, and CRTFQ open a file or 
device and relate the specified channel number to that file or device: 


¢ OPNFQ opens a file or device for input 

e CREFQ creates a file, that is, opens a file or device for output 
e CRBFQ creates a binary (executable) output file on disk 

e CRTFQ creates a temporary file on disk 


The directives .READ and .WRITE transfer data between memory and a device or 
file specified by channel number. 


The CLSFQ (close) and RSTFQ (reset) subfunctions of CALFIP close a device or 
file and free the associated channel number so it can be used with another device 
or file. 


Directives That Support I/O 


The file string scan (.FSS) directive is useful for programs that process files 
specified by a terminal user. The .FSS directive examines a string of characters 
and, if it is a valid RSTS/E file specification, converts it to the FIRQB format 
used to open a file. Thus, your program can accept a typed string from the job’s 
terminal and use .FSS to convert the string to the FIRQB format to do I/O on the 
file. 

You can use the LOKFQ subfunction of CALFIP to search for disk files that meet 
wildcard file specifications. For example, you could search an account on disk for 
all files with names beginning with the characters DD. 


3.2 Trap Handling with Supervisor Mode 


Although asynchronous I/O calls (READA and .WRITA) are illegal for a task 
using supervisor mode, other traps may require handling by a task using 
supervisor mode. The legal asynchronous system traps for supervisor-mode tasks 
are: 


e FPP exception 
e Ctrl/C interception 
e all forms of Synchronous Service Traps (SSTs) 


The trap service routines for these may be located in either user or supervisor 
~ mode. If the service routines reside in supervisor mode, they must adhere to 
additional requirements that their user mode counterparts do not need: 


e The service routine must exit via either the SSTX$ or ASTX$ calls. In 
user mode only, service routines can clean the PC & PSW off the stack and 
continue without returning, but if supervisor mode in use, tasks must use an 
exit call. Note that the hardware prohibits an RTI instruction from returning 
a task to supervisor mode from a service routine in user mode. 


¢ Routines located in supervisor space must obey all the rules of supervisor 
library routines such as not calling user mode routines and having no data 
within the code. 
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The task tells RSTS/E the space of the service routine when the respective service 
vectors are set up. The following calls set up the trap service vectors for the task: 


e FPPA$—floating point exception 

e SCCA$—Ctrl/C interception 

e SVTK$—SST trap vector table 

¢ SVDB$—SST debugging trap vector table 


In the FPPA$ and SCCA$ calls, the task issues a single address vector. If bit 
0 of the vector is zero, the service routine is in user space. If bit 0 is 1 (an odd 
address vector), the routine is in supervisor space. 


In the SVTK$ and SVDB$ calls, the task issues a list of vectors associated with 
the different events (BPT etc.). Bit 0 in each of the individual service routine 
vector addresses gives the mode the routine is in, but in a different way from 
FPPA$ and SCCA$. If the vector entry is even, the SST routine executes in the 
same mode (either user or supervisor) that the processor was in when the SVIK$ 
or SVDB$ call was issued. If the vector entry is odd, the SST routine executes in 
the other mode. 


For example, if the processor is in supervisor mode when an SVTK¢$ is issued 
and the vector is odd (bit 0 set), the SST routine executes in the user mode. This 
method is the same as RSX-11M-PLUS. It lets the individual SSTs be different 
modes at the same time (BPT in user and address trap in supervisor). Bit 0, 
which is the flag(s), is a member of the vector list, not the address pointer to the 
vector list. 
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3.3 .AST—Enable/Disable AST Delivery 
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Form 
AST 


Function 


The .AST directive has two functions: disable AST delivery and enable AST 
delivery. The .AST disable function stalls all AST deliveries from the monitor 
until the user explicitly enables them with the .AST enable directive. 


Privileges Required 
None 


Data Passed 


The only data passed for this directive is in byte 0 of the XRB. If zero, enable 
AST deliveries. If minus one, disable AST deliveries. 


Data Returned 


Except for a possible error code in byte 0 of the FIRQB, this directive does not 
return any meaningful data. 


Errors 


BADFUO Illegal function code. 


3.4 .ASTX—Exit from AST Routine 


Form 
ASTX 


Function 


The .ASTX directive is similar to a RETURN in a normal subroutine. It instructs 
the monitor that the asynchronous routine has completed and that control should 
return to the job at the point it was interrupted. All AST routines must finish 
with a .ASTX directive. 


When an AST routine issues the .ASTX directive, the PSW previously stored on 
the user’s stack is validated. The PSW is forced into the standard mode (previous 
user/current user mode, register set 1, and priority 0). The PC and PSW are then 
used to return control to the program at the point where it was interrupted. 


The XRB and bytes 0, 6, and 7 of the FIRQB are restored. If the user has altered 
the PC, PSW, or destroyed the stack contents, no specific error is returned. 
Instead, bad PC and/or stack causes fatal errors which are handled in the usual 
way (entry to P.BAD in the RTS). 


The AST routine must make sure all general registers (RO to R5) and the stack 
pointer have the same contents as on entry to the AST routine. In addition, 

if any part of the FIRQB other than bytes 0, 6, and 7 has been used, the AST 
routine must restore the contents of the FIRQB to what it had on entry. Failure 
to observe these rules may produce unexpected results. 
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3.5 CALFIP — Call the File Processor 
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Form 
CALFIP 


Function 


The CALFIP directive to the RSTS/E monitor handles housekeeping necessary for 
input/output on RSTS/E. For example, CALFIP lets you open a channel for file or 
device I/O. 


You select the particular function by setting a function field in the FIRQB (at 
offset FQFUN). Other parameters are also passed to the monitor in the FIRQB, 
depending on the function requested. 


Table 3—2 lists the CALFIP subfunctions by function code. The sections following 
Table 3—2 describe the subfunctions in alphabetical order. | 


Table 3-2: Summary of CALFIP Subfunctions 


FQFUN 
Value | 
(Octal) Mnemonic Action Performed (BASIC-PLUS Equivalent) 
0 CLSFQ Close an open channel (CLOSE) 
2 OPNFQ Open a channel (OPEN FOR INPUT) 
4, CREFQ Create/extend a file (file-structured OPEN FOR OUTPUT) 
6 DLNFQ Delete a file by name (KILL) 
10 RENFQ Rename a file (NAME...AS) 
12 DIRFQ Get directory information 
14 UUVOFQ Process UUO 
16 ERRFQ Get error message text 
20 RSTFQ Reset (close) a channel or all channels (except channel 0) 
22 LOKFQ Look up a file 
24 ASSFQ Allocate a device 
26 DEAFQ Deallocate a device 
30 DALFQ Deallocate all devices 
32 CRTFQ Create/extend a temporary file on disk | 
34 CRBFQ Create/extend a compiled image file on disk (file-structured 


OPEN FOR OUTPUT, protection code bit 6 always set) 
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ASSFQ (Allocate a Device) 


Form 


MOVB #ASSFQ, FIRQB+FQFUN 


(Set up 


CALFIP 


FIROB to define device) 


Function . 


The ASSFQ subfunction reserves a physical device for a job or transfers assign- 
ment of a currently owned device to another job. For host-initiated LAT ports, 
this directive initiates a connection to the server currently assigned to the port. 


Privileges Required 


DEVICE to allocate a device for the current job if the requested device is re- 
stricted. HWCTL to seize a device or reallocate a device to a job in another 


account. 


Data Passed 


Mne- 
monic 


FQFUN 


FIRQB+FQFUN 


FIRQB 


Octal Octal 


Mne- 


Offset Offset monic 


LIIIITTTT TTT TTT TI 


ASSFQ (= 24) PITTLTTAT 


PTA ATA LA ETL ITT ATT EAT 


LIIIIIIITT ITT TTT TTT 


IIIT 


=0,assign;<>0,job no. 


| PIII TTT TT TTT 


DOS or ANS (1 word RADS50) or 0 (magtape) 


LTIITIITIIT IAI TTT TT 


PTT TALAT LATA TAAL TAT A 


PITTA TAA AT Ad dada ad 


PITTI IIIT ATT 


device name (2 ASCII characters) 


EPEAT TALLTOLAAL IT A TALS 
EF TALAALAT TT AST ALT Idea 


FQNAM1 


FQEXT 


FQMODE 


FQDEV 
FQDEVN 


The function code ASSFQ (octal value = 24). 
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FIRQB+FQNAM1 This byte is set to zero to indicate an assign; if nonzero, it is used 
as the job number to which the device is to be reassigned. The 
high byte of this word (FIRQB+11) must be set to zero. If you do 
not have HWCTL privilege, you can reassign a device only to a job 
that is logged in to the same account as your current account. 


FIRQB+FQEXT When the device is magnetic tape, this word can contain either 
DOS or ANS in RAD50 format, to indicate DOS or ANSI label 
format for the tape drive. It can also be set to zero to indicate the 
system default for the drive. 


FIRQB+FQMODE This word contains the mode to use when allocating the device. 
Valid modes are: 
Mode Description 
100001 Used to allocate a device that is currently al- 
located to another user. This is a snagging 


allocation, available to users with the HWCTL 
privilege. | 


100002 Only used when allocating a LAT port and used 
to tell the LAT driver that the request to initiate 
the connection should not be queued if the remote 
port is not available. 


100004 Only used when allocating a LAT port and used to 
tell the LAT driver that the request to initiate the 
connection should be queued if the remote port is 


not available. 


0 Used when you do not want a snagging allocation 
and when you want the LAT driver to use the 
port’s default queueing setting. 


FIRQB+FQDEV Device name, as two ASCII characters. 


FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in FIRQB+FQDEVN+1 indicates an explicit device unit number. 
A zero value in FIRQB+FQDEVN+1 indicates no unit number. 


Data Returned 


Byte 0 of the FIRQB contains a possible error code. FIRQB+FQFIL contains 
the previous owner of the device. If the device is a keyboard, FIRQB+FQFIL+1 
contains a 0 for an interactive keyboard or a 1 for a LAT port used for host- 
initiated connections. 


Errors 
For Assign (byte at FIRQB+FQNAM1 = 0): 


NODEVC The device name specified at FIRQB+FQDEV is not a valid device name. 


NOTAVL The device and unit specified exists on the system, but the attempt to 
reserve it is prohibited because: 


e The device is currently reserved by another job. 
e The device or its controller has been disabled by the system manager. 
e The device is a keyboard line for a pseudo keyboard only. 


NOBUFS No buffers available to initiate the connection to the terminal server. 
For Reassign (byte at FIRQB+FQNAMI1 # 0): 


BDNERR The job number specified does not exist. 
INUSE The device specified is currently open or has an open file. 
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NODEVC The device name is a logical device name for which a physical device is not 
currently assigned. 


NOTAVL (See previous description for Assign.) 


PRVIOL You do not have HWCTL privilege and you tried to reallocate a device to a 
job that is logged in to an account other than your current account. 


Example 


The following code reassigns magnetic tape unit 0 (MT0:) to job 12: 


MAGT: -ASCII 
CALL 
MOVB 
MOVB 
MOV 
MOV 
CLRB 
MOVB 
CALFIP 
TSTB 
BNE 


/MT/ 

CLRFQB 

#ASSFQ, FIRQB+FOQFUN 
#12.,F IRQB+FQNAM1 
#*RANS , FIRQB+14 
MAGT, FIRQB+FQDEV 
FIRQB+FQDEVN 

#377,F IRQB+FQDEVN+1 


FIRQB 
ERRTN 


,CALL ROUTINE TO CLEAR FIRQB 
7;SET FUNCTION CODE 

; ASSIGN TO JOB 12 

; ANSI-LABEL TAPE 

;MAGTAPE DEVICE 

;UNIT NO. O 

;UNIT NO. REAL 


; ANY ERRORS? 
BRANCH TO PROCESS ERROR 


See the section entitled "Programming Hints" for information on the CLRFQB 


routine. 
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3.5.2 CLSFQ (Close a Channel) 


Form/Example 


CHANO=8. : Set value for channel 
MOVB #CLSFQ, FIRQB+FQFUN e Set function code in FIRQB 
MOVB #CHANO*2, FIRQB+FOFIL ; Set channel 8 for CLOSE 
CALFIP : Execute monitor directive 
Function 


The CLSFQ function closes a channel. The specific action taken depends on the 
device or file that was previously opened on the channel and whether it was 
opened for input or output, as well as the mode with which it was opened. For 
example, closing a channel on which a magnetic tape was opened for input in 
file-structured mode causes the monitor to position the tape at the end-of-file 
(EOF). See the RSTS/E Programming Manual for a description of the actions 
taken on closing various devices/files. 


Requesting CLSFQ for a channel that is not currently open returns with no action 
taken and no error is indicated. 


Privileges Required 


None 


Data Passed 


FIRQB 

Mne- Octal Octal Mne- 
monic Offset Offset monic 

(en _*d 

7 6 

11 10 

13 12 

15 14 

17 16 

21 20 

23 22 

25 24 

27 26 

31 30 

33 32 

35 34 

37 36 
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FIRQB+FQFUN The function code CLSFQ (octal value = 0). 
FIRQB+FQFIL Channel number times two; defines the channel to be closed. 


Data Returned 

Except for a possible error in byte 0 of the FIRQB, the CLSFQ function of 
CALFIP does not return any meaningful data. 

Errors 


All errors with the CLSFQ function of CALFIP are device-dependent. See 
Appendix A for a full list of errors. 


Example 

The following MACRO code closes the file or device on channel 12: 

CALL CLRFQB ;CLEAR FIRQB 

MOVB #CLSFQ, FIRQB+FQFUN ;SET FUNCTION CODE IN FIRQB 
MOVB #12.*2, FIRQB+FOQFIL ;SET CHANNEL 12 FOR CLOSE 
CALFIP ;EXECUTE MONITOR DIRECTIVE 
TSTB FIRQB ;TEST BYTE O FOR ERROR 

BNE ERRTN ;BRANCH TO PROCESS ERROR 


See Programming Hints for information on the CLRFQB routine. 
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3.5.3 CRBFQ (Create a Binary [Executable] File and Open It on a Channel) 


Form 
MOVB #CRBFQ, FIRQB+FQFUN :SET FUNCTION CODE 


(Set parameters in FIRQB appropriate to device) 


CALFIP 


Function 


The CRBFQ function creates and opens a binary (executable) file. It is identical 
to the CREFQ function, except that the protection code is automatically set to 
indicate an executable file, and the file must be opened on a disk device. 


Privileges Required 


TUNE to set caching mode. SYSIO to set the privileged-program bit (bit 7 in 
FQPROT). A matching PPN, GWRITE, or WWRITE, and/or SYSIO to create or 
rename a file. You also need write access (by protection code, GWRITE, WWRITE, 
and/or SYSIO) to supersede an existing file. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 LIIIIITATTI TTT TTT TT 


CRBFQ (= 34) PPITTTTTAT 


FQFUN 3 
FQSIZM 5 


project number programmer number 


file name in RAD50 format 


2 
4 FQFIL 
6 


7 FQPPN 


11 110  FQNAM1 


13 (2 words) 


pmo 
device unit number 


15 14 FQEXT 


17 16 FQSIZ 
21 
23 22 FQMODE 
25 
FQPROT 27 26 FQPFLG 
31 30 FQDEV 


33 


32 FQDEVN 
35 34 FQCLUS 


37 36 FQONENT 


3-18 CALFIP—CRBFQ 


FIRQB+FQFUN 
FIRQB+FQFIL 


FIRQB+FQSIZM 


FIRQB+FQPPN 


FIRQB+FQNAM1 
FIRQB+FQEXT 
FIRQB+FQSIZ 


FIRQB+FQMODE 


FIRQB+FQPROT 


FIRQB+FQDEV 


FIRQB+FQDEVN 


FIRQB+FQCLUS 


The function code CRBF@Q (octal value = 34). 


Channel number times two; defines the channel upon which the 
file is to be opened. 


On other types of create opens, this byte contains the most signifi- 
cant bits (MSB) of the file size. Executable (binary) files cannot be 
greater than 65,535 blocks so this byte must always be passed as 
zero. 


The PPN with which the file is to be created. The project number 
is in the high byte (FQPPN+1) and the programmer number in 
the low byte (FQPPN). A value of zero in both bytes defaults to 
the PPN under which the calling program is running. 


The file name created, as two words of RAD50 data. 
The file type, as one word of RAD50 data. 


The desired file size, in 512-byte blocks. The file is preextended to 
the specified size; that is, the space for the file is allocated when 
the file is opened, rather than as it is written. 


The mode with which the file is to be opened; values and actions 
taken are as described for the MODE modifier in file-structured 
OPEN FOR OUTPUT statements for disk, as the RST'S/E 
Programming Manual describes. If a mode value is used, bit 

15 of this word must be set to 1. 


_ File protection code; values for this field define read/write and 


execute access to the created file (see the RST'S/E System User’s 
Guide). If you want a default protection code, then set a full 
word of zeros at FIRQB+FQPFLG. In this case, either the system 
default for protection code will be used, or, if the CRBFQ will be 
deleting a previously existing file with the same file name, type, 
PPN, and device, the file protection code of the previously existing 
file will be used. 


To assign a specific file protection code, a nonzero value is passed 
in byte FIRQB+FQPFLG (by convention, 255) and the specific file 
protection code in byte FIRQB+FQPROT. Bit 6 is automatically 
set, indicating that the file is executable. The RSTS/E System 
User’s Guide describes the protection codes for executable files. 


The device name is passed here as two ASCII characters; it must 
be a disk device. If this word is zero, the public disk structure is 
assumed. 


The device unit number is passed here in binary. A nonzero value 
in FQDEVN+1 indicates an explicit device unit number. A zero 
value in FQDEVN+1 indicates no unit number. 


This parameter has the same function as the CLUSTERSIZE 
option in BASIC-PLUS. The BASIC-PLUS Language Manual 
describes the CLUSTERSIZE option for disks. 
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FIRQB+FQNENT 


Data Returned 


Mne- Octal 
monic Offset 


Device cluster number for placement of block 1 of the file. When 
you are creating a new file, you can place block 1 of the file on 
a particular block by specifying the disk device cluster number 
in this word. If this word is zero, no placement is done. If it 

is nonzero, the monitor will try to place the file at the specified 
device cluster or as near after it as possible. 


If the first block of the file can be placed at or after the specified 
device cluster number, the monitor sets a bit in the file’s entry in 
the User File Directory (UFD). If the first block of the file cannot 
be placed at or after the specified device cluster number, the file 

is placed at the lowest free block on the disk, the bit in the file’s 

entry in the UFD is not set, and no error is returned. 


A value of -1 specifies the center of the disk; a value of -2 means 
immediately after the directory. 


FIRQB 
Octal Mne- 
Offset monic 


| . 
FQSIZM 5 (always 0) channel number * 2 4 FQFIL 
11 file name in RAD50 format 10 FQNAM1 
13 (2 words) 12 
FIRQB+FQJOB Current job number times two. 
FIRQB+FQFIL Channel number times two; defines the channel on which the file 
is open. 
FIRQB+FQPPN The PPN under which the file is open. An actual PPN is returned 
here even if this word was passed as zero. 
FIRQB+FQNAM1 The file name created, as two words of RAD50 data. 
FIRQB+FQEXT The file type created, as one word of RAD50 data. 
FIRQB+FQSIZ The size to which the file was preextended, in 512-byte blocks. 
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FIRQB+FQBUFL 


FIRQB+FQFLAG 


FIRQB+FQPFLG 


FIRQB+FQPROT 


FIRQB+FQDEV 


FIRQB+FQDEVN 


FIRQB+FQCLUS 


Errors 


Reasonable buffer size for disk reads and writes, in bytes. (Always 
512 for disk.) 


Description of the device just opened (the same information as 
the BASIC-PLUS STATUS variable). The low byte contains the 
device’s handler index, always zero (DSKHND) for disk. The high 
byte contains a set of status flags, irrelevant here since the device 
is always disk. (See the OPNFQ subfunction for more information 
on these settings.) 


The file cluster size, modulo 256. That is, a file cluster size of 
256 is indicated by zero. This is the same as the value passed at 
FIRQB+FQCLUS, except that it is returned in a byte instead of a 
word. 


The protection code of the file. Bit 6 is 1, and bits 5 through O are 
as passed. Bit 7 is as passed if the caller has SYSIO privilege; 
otherwise it is 0. 


The device name of the disk device, as two ASCII characters. The 
actual device name is returned here, even if this word was passed 
as zero. 


The device unit number. The actual unit number is returned here, 


even if FIRQB+FQDEVN+1 was passed as zero. 


The file identification index of this file. This word is significant 
mainly in that it can be used in place of the file name in sub- 
sequent opens of the file on disk. You can open the file with 
the OPNFQ subfunction of CALFIP using an explicit PPN in 
FIRQB+FQPPN, a zero word in FIRQB+FQNAM1, an explicit 
device name in FQDEV and FQDEVN, and the file identification 
index in FIRQB+FQNAM1+2. 


Note that there is no performance gain for using the file iden- 
tification index instead of the file name. The file identification 
index is provided for compatibility with RSX. Furthermore, the file 
identification index is changed when the REORDR utility is run 
(see the RSTS/E System Manager’s Guide). 


NOTCLS The specified channel is already open. It must be closed before it can be 
opened again. 

PRVIOL The specified device is not a disk device. The CRBFQ function can be 
executed only for a disk device. 


QUOTA Extending the file causes the disk quota to be exceeded. This error does not 
occur if the user has EXQTA privilege. 


XXXXKX Other errors are device-dependent. See Appendix A for a full list of possible 
error codes. 
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Example 


The following MACRO code sets up the FIRQB for the CRBFQ function of 
CALFIP. The PPN is set to 2,210; the file name and type are set to FILNAM.TYP. 
The protection code is set such that the file is read/write-protected against ev- 
eryone but the caller (user with PPN 2,210), and execute-protected against all 
but the caller and those in the caller’s project (users with project number = 2). 
The file is opened on disk unit 2 (DK2:). File size and cluster size are not spec- 
ified. The cluster size defaults to the pack cluster size and the file size is not 


preallocated. 
DK: .ASCII /DK/ 
CALL CLRFQB ;CLEAR FIRQB 
MOVB #CRBFQ, FIRQB+FQFUN ;SET FUNCTION CODE 
MOVB #4*2, FIRQB+FQFIL ;SET CHANNEL = 4 
MOVB #2, F IRQB+FQPPN+1 ;SET PROJECT NUMBER =2 
MOVB #210.,FIRQB+FOPPN ;SET PROG. NO.=210. 
MOV #°RFIL, FIRQB+FQNAM1 ;SET FILE NAME AND 
MOV #°RNAM,FIRQB+FQNAM1+2 ;TYPE TO 
MOV #°RTYP , FIRQB+FQEXT ; "FILNAM. TYP" 
MOVB #<8.+16.+32.>,FIRQB+FQPROT ;SET PROTECTION CODE 
MOVB #255.,FIRQB+FQPFLG ;SET PROTECTION CODE REAL 
MOV DK, FIRQB+FQDEV ;SET DEVICE TO DISK, 
MOVB #2, FIRQB+FQDEVN ;UNIT 2 
MOVB #255.,FIRQB+FQDEVN+1 ; (EXPLICIT DEVICE NO.) 
CALFIP 


See Programming Hints for information on the CLRFQB routine. 
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3.5.4 CREFQ (Create a File and Open It on a Channel) 


Form 


MOVB #CREFQ, FIROB+FQFUN ;SET FUNCTION CODE 
(set parameters appropriate to device) 


CALFIP 


Function 


The CREFQ function performs the same action as a file-structured OPEN FOR 

OUTPUT statement in BASIC-PLUS. Parameters defining the device, file name 
and type, protection code, mode, file size, and cluster size can be used by setting 
values in the FIRQB. The choice depends upon the device. 


For example, CREFQ with a file name and type on a magtape device with mode 
= 128 causes an OPEN for APPEND operation. A search for an existing file with 
the specified name and on the specified device is made; the file would have to 

be the last file on the tape. When found, the tape is positioned after the last 
record in the file, ready for data to be written and appended. The RSTS/E 
Programming Manual describes the file-structured OPEN for OUTPUT operation 
for the various devices. 


Privileges Required 


TUNE to set caching mode. SYSIO to set the privilege bit (bit 7 in FQPROT). A 
matching PPN, GWRITE, WWRITE, and/or SYSIO to create or rename a file. You 
also need write access (by protection code, GWRITE, WWRITE, and/or SYSIO) to 
supersede an existing file. 
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Data Passed 


Mne- Octal 
monic Offset 


FQFUN 3 


FIRQB 
Octal Mne- 
Offset monic 


osizs | MSB of le siz FOFIL 


25 | 


file name in  RADSO rs 5 FQNAM1 


ae wONgS) 


fil type i in ) RADSO | format (1 word) FQEXT 


LsB of ile size FQSIZ 


FQMODE 


TT 


raprot 27 | fle protection FoPrLe 


31 


35 


device name (2 ASCII! characters) | FQDEV 


33 devices unit number FQDEVN 


“file clustersize FQCLUS 


37 device cee anbee = first eek | FQNENT 


FIRQB+FQFUN 
FIRQB+FQFIL 


FIRQB+FQSIZM 


FIRQB+FQPPN 


FIRQB+FQNAMI1 
FIRQB+FQEXT 
FIRQB+FQSIZ 
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The function code CREFQ (octal value = 4). 


Channel number times two; defines the channel upon which the 
file is to be opened. 


For large disk files (greater than 65,535 blocks), this byte contains 
the most significant bits (MSB) of the file size. See FIRQB+FQSIZ, 
for a discussion of the entire 24-bit field used for large files on 
disk. 


The PPN with which the file is to be created. The project number 
is in the high byte (FIRQB+FQPPN+1), and the programmer 
number in the low byte (FIRQB+FQPPN). A value of zero defaults 
to the PPN under which the calling program is running. 


The file name to create, as two words of RAD50 data. 
The file type, as one word of RAD50 data. 


The desired file size, in 512-byte blocks. This parameter is rel- 
evant only for disk and ANSI magtape files. For disk files, this 
word forms the least significant bits (LSB) of the file size. It is 
combined with the byte at FIRQB+FQSIZM to form a 24-bit in- 
teger. The disk file is automatically preextended to the indicated 
size. (That is, the space for the file is allocated when the file is 
opened, not as it is written.) If preextending is not desired then 
this value and FIRQB+FQSIZM should be zero. 


Hor ANSI magtape, this word has the same function as the 
FILESIZE option in BASIC-PLUS (see the RSTS/E Programming 
Manual). 


FIRQB+FQMODE 


FIRQB+FQPROT 


FIRQB+FQDEV 


FIRQB+FQDEVN 


FIRQB+FQCLUS 


FIRQB+FQNENT 


The mode with which the file is to be opened; values and actions 
taken for specific devices are as described for the MODE modifier 
for file-structured OPEN for OUTPUT statements in the RSTS/E 
Programming Manual. If a mode value is used, bit 15 of this word 
must be set to 1. 


File protection code; values for this field define subsequent read 
and write access to the opened file (see the RST'S/E System User’s 
Guide). If you want a default protection code, then set a full 
word of zeros at FIRQB+FQPFLG. In this case, either the system 
default for protection code will be used, or, if the CREFQ will be 
deleting a previously existing file with the same file name, type, 
ppn, and device, the file protection code of the previously existing 


file will be used. 


To assign a specific file protection code, put a nonzero value in 
byte FIRQB+FQPFLG (by convention, 255) and the specific file 
protection code in byte FIRQB+FQPROT. This allows an explicit 
file protection code of 0. 


The device name is passed here as two ASCII characters. A zero 
word indicates the public disk structure. 


The device unit number is passed here in binary. A nonzero value 
in FIRQB+FQDEVN+1 indicates an explicit device unit number. 
A zero value in FIRQB+FQDEVN+1 indicates no unit number. 


This parameter has the same function as the CLUSTERSIZE 
option in BASIC-PLUS. It is relevant only for disk files and ANSI 
magtape files. A description of the CLUSTERSIZE option for 
disk is given in the BASIC-PLUS Language Manual, for ANSI 
magtape, in the RSTS/E Programming Manual. 


For disk files, the device cluster number for placement of block 

1 of the file. When creating a new file, you can place block 1 of 
the file on a particular block by specifying the disk device cluster 
number in this word. If this word is zero, no placement is done. If 
it is nonzero, the monitor will try to place the file at the specified 
device cluster or as near after it as possible. 

If the first block of the file can be placed at or after the specified 
device cluster number, the monitor sets a bit in the file’s entry in 
the UFD. If the first block of the file cannot be placed at or after 
the specified device cluster number, the file is placed at the lowest 
free block on the disk, the bit in the file’s entry in the UFD is not 
set, and no error is returned. 

A value of -1 means the center of the disk; a value of -2 means 
immediately after the directory. 
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3-26 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LTIIITIATI ATTA TT I 
| LIMIT | current job no. * 2 


| MSB of file size channel number* 2 | 


file name in RAD50 format 


1 


3 2 FQJOB 


FQSIZM 5 4 FOFIL 
7 6 FQPPN 


11 10 FQONAM1 


13 (2 words) 


| file type in RAD50 format (1 word) 
LSB of file size 


15 14. FQEXT 


17 16 FQSIZ 


21 20 FQBUFL 


protection aade 


(as passed) 


NOTE 


For nondisk devices, the relevant information returned with the 
CREFQ subfunction is in the two words at FIRQB+FQBUFL and 
FIRQB+FQFLAG., All other words are simply returned as passed. 


23 22 FQMODE 


25 24 FQFLAG 


FQPROT 27 


26 FQPFLG 
31 30 FQDEV 
33 32 FQDEVN 
35 34 FQCLUS 


37 36 FQONENT 


FIRQB+FQJOB Current job number times two. 

FIRQB+FQFIL Channel number times two; defines the channel on which the file 
is open. 

FIRQB+FQSIZM For large files, this byte contains the MSB of the size to which the 


file was preextended, in 512-byte blocks. This byte is combined 
with the word at FIRQB+FQSIZ to form a 24-bit field giving the 


file size. 
FIRQB+FQPPN The PPN under which the file is open. An actual PPN is returned 
here even if this word was passed as zero. 
FIRQB+FQNAM1 The file name created, as two words of RAD5O data. 
FIRQB+FQEXT The file type created, as one word of RAD5O data. 
FIRQB+FQSIZ The size to which the file was preextended, in 512-byte blocks. 
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FIRQB+FQBUFL Reasonable buffer size for this device, in bytes. If you are doing 
device-independent I/O (that is, if you do not want to keep track 
of which device is being opened and perform specific opens, reads, 
and writes, depending on the device), this value is the monitor’s 
best guess for a buffer size to use in subsequent reads and writes 
on the opened channel. (See the .READ and .WRITE directives.) 


FIRQB+FQFLAG Description of the device just opened (same information as the 
| BASIC-PLUS STATUS variable). The low byte contains the 
device’s handler index. There is one unique handler index for all 
device types. The high byte contains a set of status flags to allow 
for device-independent I/O routines. 


DDNFS 
DDRLO 
DDWLO 
FLGPOS 
FLGMOD 
FLGFRC 
FLGKB 
FLGRND 


15 14 13 12 11109 8, 7 0 
| device-type fiags | device handler index | 


High Byte — Device-Type Flags 


The bits in the high byte of the flags word are set to indicate the type of file or device just 
opened: 


FLGRND =1 The device or file is random-accegs. 


= 0 The device or file is sequential. 
FLGKB i | The file or device is a terminal-type file or 
device (or is generically a terminal). 
= 0 The file or device is not a terminal-type file or 
device. 


FLGFRC =1 The file or device is byte-oriented. That is, 
the .READ and .WRITE directives handle 
data in byte units. 


=0 The file or device is block-oriented. The 
-READ and .WRITE directives handle data in 
block units. 


FLGMOD =1 The file or device accepts modifiers in .READ 
and .WRITE directives. 


= 0 The file or device does not accept modifiers in 


-READ and .WRITE directives. 
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FLGPOS =1 The file or device keeps track of its horizon- 
tal position and expands characters such as 
TAB into whatever is appropriate for the 
file or device. You can determine the cur- 
rent horizontal position with the .POSTN 
directive. 
= 0 The file or device does not keep track of its 
horizontal position. 
DDWLO =] The file or device has been write-locked (with 
the mode value in the open) or is generically 
a read-only device. 
= 0 The file or device is not write-locked. 
DDRLO = The device is generically a write-only device. 
= 0 The file or device is not read-locked. 
DDNFS =] The file or device is non-file-structured (or is 
generically not a file-structured device). 
= 0 The file or device is file-structured. 


Low Byte — Device Handler Index 


Bits 0-7 of the flags word contain a handler index that indicates the generic kind of device. 
The currently defined values follow. 


Octal Symbol Meaning 
Value 
0 DSKHND All disks 
2 TTYHND All terminals 
4 Reserved 
6 LPTHND _ All line printers 
10 Reserved 
12 Reserved 
14 CDRHND Card reader 
16 MTAHND Magnetic tape 
20 PKBHND Pseudo keyboards 
22 RXDHND Flexible diskettes 
24 Reserved 
26 NULHND The null device 
30-36 Reserved 
40 KMCHND KMCil 
42 IBMHND _ IBM interconnect 
44 Reserved 
46 DMPHND DMP11/DMV11 device 
50 ETHHND Ethernet device 

FIRQB+FQPFLG The file cluster size, modulo 256. That is, a file cluster size of 
256 is indicated by zero. This is the same as the value passed at 
FIRQB+FQCLUS, except that it is returned in a byte instead of a 
word. 

FIRQB+FQPROT The protection code of the file. Bit 7 is as passed if the caller has 


SYSIO privilege, and 0 otherwise; bits 6 to 0 are as passed. 
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FIRQB+FQDEV 


FIRQB+FQDEVN 


FIRQB+FQCLUS 


Errors 


The device name of the disk device, as two ASCII characters. The 
actual device name is returned here, even if this word was passed 
as zero. 


The device unit number. The actual unit number is returned here, 
even if FIRQB+FQDEVN+1 was passed as zero. 


The file identification index of this file. This word is significant 
mainly in that it can be used in place of the file name in sub- 
sequent opens of the file on disk. You can open the file with 
the OPNFQ subfunction of CALFIP using an explicit PPN in 
FIRQB+FQPPN, a zero word in FIRQB+FQNAM1, and the file 
identification index in FIRQB+FQNAM1+2. 


Note that there is no performance gain for using the file identi- 
fication index rather than the file name. The file identification 
index is provided for compatibility with RSX. Furthermore, the file 
identification index is changed when the REORDR utility is run 
(see the RST'S/E System Manager’s Guide). 


NOTCLS The specified channel is already open. It must be closed before it can be 
opened again. 


QUOTA Extending the file causes the disk quota to be exceeded. This error does not 
occur if the user has EXQTA privilege. 


XXXXKX Other errors are device-dependent. See Appendix A for a full list of errors. 


Example 


The following MACRO code sets up the FIRQB for a CREFQ that opens a file 
called FILE01.LST on the public disk structure. (The assumption here is that 
previous code has filled the FIRQB with zeros, so the words at FIRQB+FQDEV 
and FIRQB+FQDEVN are zero, indicating the public disk. Similarly, the mode 
(FIRQB+FQMODE) and cluster size (FIRQB+FQCLUS) are zero, indicating nor- 
mal read/write and the default cluster size.) A protection code of 56 is assigned 
(write-protected against all but the owner, read-protected against all but those in 


the owner’s project). 


MOVB | #CREFQ, FIRQB+FQFUN ; Set function code in FIRQB 
MOVB #5*2, FIROB+FQFIL ; Set channel = 5 

MOV #°*RFIL, FIRQB+FQNAM1 ; Set file name 

MOV #*REO1, FIRQOB+FQNAM1+2 : and type to 

MOV #°“RLST, FIRQB+FQEXT ; FILEO1L.LST 

MOVB #56.,F IRQB+FQPROT ; Set protection code to 
MOVB #255.,F IRQB+FOQPFLG ; explicit protection code 
CALFIP 
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3.5.5 CRTFQ (Create and Open a Temporary File) 


Form 


MOVB #CRTFQ, FIRQB+FQFUN 
(set appropriate parameters) 


CALFIP 


Function 


The CRTFQ function can be used to create and open a temporary file on disk. 
The file is temporary only in that the monitor generates a file name and type 
for the file, which is recognized by the LOGOUT utility, and sets the IGNORE 
attribute for the file, which is recognized by BACKUP. LOGOUT destroys such 
files when the user logs out; the monitor does not inherently destroy temporary 
files created with CRTFQ. 


Most parameters relevant on an open are defaulted. You do not define or refer to 
the file by name; subsequent read and write operations refer to the channel on 
which the temporary file is open. 


In addition to the function code, you specify a channel and, if desired, a file 

size and/or file cluster size. If an explicit cluster size is specified, it is used. A 
specified file size may or may not be used. The monitor attempts to reuse an 
existing temporary file for the same job by simply reopening that file. In this 
case, the file’s size is the size of the previous file. If no previous temporary file 
for the job exists, or if one does exist but is already in use by somebody else, then 
a new file is created, with the specified file size. A new file is also created if an 
explicit device name or cluster size is given. 


Privileges Required 


TUNE to set caching mode. You also need write access (by protection code, 
GWRITE, WWRITE, and/or SYSIO) to supersede an existing file. 
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Data Passed 


Mne- 


FQFUN 3 
FQSIZM5 


FIRQB 


Octal Octal 
monic Offset 


1 


iti 
ee ee 


LIITTITIII IITA TIT 


device name (2 ASCII characters) 
Tesunerse 


7 


11 


13 


15 


17 


21 


23 


25 


27 


31 


33 


35 


37 


Mne- 


Offset monic 


FQFIL 


FQSIZ 


FQMODE 


FQDEV 
FQDEVN 
FQCLUS 


FQNENT 


FIRQB+FQFUN 
FIRQB+FQFIL 


FIRQB+FQSIZM 


FIRQB+FQSIZ 


FIRQB+FQMODE 


FIRQB+FQDEV 


The function code CRTFQ (octal value = 32). 


Channel number times two; defines the channel on which the file 
is to be opened. 


For large disk files (greater than 65,535 blocks), this byte contains 
the MSB of the file size. See FIRQB+FQSIZ, for a description of 
how the entire 24-bit field is used. 


This word contains the LSB of the file’s size in 512-byte blocks. 
(It is combined with the byte at FIRQB+FQSIZM.) The file size 
may or may not be used. If a temporary file already exists that 
is not in use, the monitor uses the space allocated to the previous 
temporary file. However, if cluster size is specified, a new file is 
created, and the file size indicated by the 24-bit file size is used. 


The mode with which the file is to be opened. Values are as de- 
scribed for the MODE modifier in OPEN for OUTPUT statements 
for disk (see the RSTS/E Programming Manual). The only rele- 
vant modes are for creating a tentative file, creating a contiguous 
file, creating a conditionally contiguous file, and for data caching. 
All other mode bits are ignored, except bit 15. If a mode value is 
used, bit 15 of this word must be set to 1. 


The device name is passed here as two ASCII characters; it must 
be a disk device. A value of zero in this word indicates _SY:, the 
public disk. 
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FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in the high byte (FIRQB+FQDEVN+1) indicates an explicit device 
unit number. A zero value in FIRQB+FQDEVN+1 indicates no 


unit number. 


FIRQB+FQCLUS File cluster size. Performs the same function as the CLUSTERSIZE 
option in BASIC-PLUS. 
FIRQB+FQNENT The device cluster number for placement of block 1 of the file on 


disk. When creating a new file, you can place block 1 of the file 
on a particular block by specifying the disk device cluster number 
in this word. If this word is zero, no placement is done. If it is 
nonzero, the monitor tries to place the file at the specified device 
cluster or as near after it as possible. 

If the first block of the file can be placed at or after the specified 
device cluster number, the monitor sets a bit in the file’s entry in 
the UFD. If the first block of the file cannot be placed at or after 
the specified device cluster number, the file is placed at the lowest 
free block on the disk, the bit in the file’s entry in the UFD is not 
set, and no error is returned. 

A value of -1 means the center of the disk; a value of -2 means 
immediately after the directory. 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
11 | file name in RAD50 format 10 FQNAM1 
13 (2 words) 12 
FIRQB+FQJOB Current job number times two. 
FIRQB+FQFIL Channel number times two; defines the channel on which the file 


18 open. 
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FIRQB+FQSIZM For large disk files (greater than 65,535 blocks), this byte contains 
the MSB of the file size in 512-byte blocks. It is combined with the 
word at FIRQB+FQSIZ to form a 24-bit field giving the file size. 


FIRQB+FQPPN The PPN under which the file is open. An actual PPN is returned 
here even if this word was passed as zero. 

FIRQB+FQNAM1 The file name created; two words of RAD50 data. 

FIRQB+FQEXT The file type created; one word of RAD50 data. 

 FIRQB+FQSIZ The size to which the file was preextended, in 512-byte blocks. 

FIRQB+FQBUFL Reasonable buffer size for disk reads and writes, in bytes. (Always 
512. for disk.) 

FIRQB+FQFLAG Description of the device just opened (the same information as 


the BASIC-PLUS STATUS variable). The low byte contains the 
device’s handler index, always zero (DSKHND) for disk. The high 
byte contains a set of status flags, irrelevant here since the device 
is always disk. See the OPNFQ subfunction for more information 
about these settings. 


FIRQB+FQPFLG The file cluster size, modulo 256. That is, a file cluster size of 
256 is indicated by zero. This is the same as the value passed at 
FIRQB+FQCLUS, except that it is returned in a byte instead of a 


word. 

FIRQB+FQPROT The protection code of the file. 

FIRQB+FQDEV The device name of the disk device, as two ASCII characters. The 
actual device name is returned here, even if this word was passed 
as zero. 

FIRQB+FQDEVN The device unit number. The actual unit number is returned here, 
even if FIRQB+FQDEVN+1 was passed as zero. 

FIRQB+FQCLUS The file identification index of this file. This word is significant 


mainly in that it can be used in place of the file name in sub- 
sequent opens of the file on disk. You can open the file with 
the OPNFQ subfunction of CALFIP using an explicit PPN in 
FIRQB+FQPPN, a zero word in FIRQB+FQNAM1, and the file 
identification index in FIRQB+FQNAM1+2. 


Note that there is no performance gain for using the file identi- 
fication index rather than the file name. The file identification 
index is provided for compatibility with RSX. Furthermore, the file 
identification index is changed when the REORDR utility is run 
on the directory (see the RST'S/E System Manager’s Guide). 


Errors 

QUOTA Extending the file causes the disk quota to be exceeded. This error does not 
occur if the user has EXQTA privilege. | 

XXXXX All other errors for this directive are device-dependent. See Appendix A for 
a full list of errors. 

Example 


The following MACRO code opens a temporary file on channel 13. Assume that 
the FIRQB has been initialized to all zeros. Hence, the temporary file is created 
on the public disk structure: 


MOVB #CRTIFQ, FIROB+FQFUN ;SET FUNCTION CODE 
MOVB #13.*2,F IRQB+FOFIL ;SET CHANNEL TO 13 
CALFIP 
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3.9.6 DALFQ (Deallocate All Devices and Deassign All User Logicals) 


Form 


MOVB #DALFQ, FIRQB+FOFUN 
CALFIP 


Function 


The DALFQ subfunction deallocates all devices currently allocated to the job and 
deassigns all user logicals assigned by the job. 


Privileges Required 


None 


Data Passed 


FIRQB 

Mne- Octal Octal Mne- 
monic Offset Offset monic 

. . 

5 ITITILALTALATLALALT A | 4 

7{. “TAT TTITII TTI AIA 6 

31 | | Dia Aa PER | 30 

FIRQB+FQFUN The function code DALFQ (octal value = 30). 


Data Returned 
The DALFQ subfunction of CALFIP does not return any meaningful data. 


Errors 
No errors are possible with DALFQ. 
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3.5.7 DEAFQ (Deallocate a Device) 


Form 
MOVB #DEAFQ, FIRQB+FQFUN 


‘(Define device to be deallocated in FIRQB) 


CALFIP 


Function 


The DEAFQ subfunction deallocates (that is, releases it for use by other jobs) a 
device from the current job. If the device is an outbound LAT keyboard, DEAFQ 
terminates any connection before deallocating the keyboards. 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
| . 
. , 
) 
11 (must = 0) | 10 FQNAM1 
FIRQB+FQFUN The DEAFQ function code (octal value = 26). 
FIRQB+FQNAM1 The word at this location must be set to zero. 
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FIRQB+FQDEV The name of the device to be deallocated, as two ASCII characters. 


FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in FIRQB+FQDEVN+1 indicates an explicit device unit number, 
while a zero value indicates no device unit number. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the DEAFQ subfunction of 
CALFIP does not return any meaningful data. 


Errors 


NODEVC The device or its type specified at FIRQB+FQDEV and FIRQB+FQDEVN is 
not part of your system configuration. 


Example 


The following code deallocates LP: from the current job: 


CALL CLRFQB ; Clear FIRQOB 

MOVB #DEAFQ, FIRQOB+FOQFUN : Set function code 
MOV #"LP, FIROB+FQDEV ; Device=line printer 
CALFIP 


See Programming Hints for information on the CLRFQB routine. 
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3.5.8 DIRFQ (Get Directory Information) 


Form 
MOVB #DIRFQ, FIRQB+FQFUN 


(Define device for the directory wanted) 


CALFIP 


Function 


The DIRFQ subfunction of CALFIP returns directory information about a disk, 
DECtape, or magtape file. Two forms of the call are available. One leaves a 
magtape file positioned at the EOF and returns the size of the file as part of the 
directory information. The second form, for magtape only, leaves a magtape file 
positioned at the beginning of the file, and does not return the size of the file. 


NOTE 


For disk directory lookup on a PPN other than that of the caller, 
DIRFQ returns only those files to which the caller has read or execute 
access. 


Privileges Required 


DEVICE to perform a directory lookup or disk lookup on caller’s account if the 
referenced device is restricted. You need read or execute access (by protection 
code, GREAD, or WREAD) to perform a disk directory lookup on another account. 
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Data Passed — Directory Lookup on Index 


Mne- Octal 
monic Offset 


1 


FOQFUN 3 | 


5 | 


7 
11 
13 

15 | 
17 
21 
23 
25 


27 


FIRQB+FQFUN 
FIRQB+FQFIL 


FIRQB+FQPPN 
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project number | programmer number | 


LAT ATTA TATA ATA A Td 


VLEATALALT ATT AAA TTA 


EN IAL IDES 
TTT LLL 
LTT TTL 


device name oe aad characters) 


TTT TELL TTL 
ETT 


FIRQB 


Octal Mne- 
Offset monic 


TTT TATA 0 


UTNTTT 


index of file to read 


2 


4 FQFIL 


6 FQPPN 


10 


LALIT TERETE AELTAT TAT ELS 


12 


FAA AT ALATA AAAL TAAL I A Td 14 


16 


ee eG Tern 20 


22 


24 


26 


| 30 FODEV 


32 FQDEVN 


34 


36 


The function code DIRFQ (octal value = 12). 


The index of the file to read. If this word is zero, the monitor 
returns data for the first file in the directory. For some positive 
value n, the monitor returns data for the n+1 file in the directory. 


For magtape, a value of zero causes the monitor to rewind the tape 
before it gets the information for the first file (by reading the label 
record of the file). The monitor then spaces the tape forward to 
the next EOF record and calculates the number of records in the 
file. The tape is left in that position. A nonzero value performs 
the same action, except that the tape is not rewound. 


For DECtape, the first call issued must have a value of zero in 
this word to read the directory blocks from the tape before reading 
the first file. Subsequent calls with this word nonzero read the 
directory from the BUFF'SYS file. (Directory information for 
DECtape is kept in this system file on disk to speed up DECtape 
file processing: see the RSTS/E Programming Manual.) 


The PPN of the directory to look up, for disk or magnetic tape. 
(The monitor does not use these bytes if the device is DECtape but 
simply returns information for each file read on the device.) 


If this word is zero and the device is disk, this directive returns 
information for the PPN under which this job is being executed. 


If this word is zero and the device is magnetic tape, this directive 
returns information for each file read, regardless of the PPN under 
which it was written. 


FIRQB+FQDEV The device name, as two ASCII characters. Must be disk, mag- 
netic tape, or DECtape. If this word is zero, the public disk 
structure (_SY:) is used. 


FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in FQDEVN+1 indicates an explicit device unit number. A zero 
value in FQDEVN+1 indicates no unit number. 


Data Passed — Speciai Magnetic Tape Lookup 


FIRQB 
Mne- Octal Octal Mnhne- 
monic Offset Offset monic 


[erro [nn _| 
Per ttiorees 
mini | 
mini | 
[Sauna wat | sevice unter | 
[ern 


FIRQB+FQFUN The function code DIRFQ (octal value = 12), 


FIRQB+FQFIL Index number of the file to be read. If this word is zero, 
information is returned for the first file in the directory. If this 
word is some positive value n, information is returned for the 
n+1 file in the directory. A value of zero causes the monitor 
to rewind the tape before getting information from the first 
file (by reading the label record). It then back spaces the tape 
one record, leaving it positioned at the beginning-of-file (BOF). 
(This action leaves the tape positioned such that an open on 
this file will succeed on a single read from tape.) 


1 


FQFUN 3 
5 
7 


11 


13 


15 


17 | 
21 
23 
25 


27 


31 30 FQDEV 


33 32 FQDEVN 


35 


37 
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FIRQB+FQPPN 
FIRQB+FQDEV 


FIRQB+FQDEVN 


Data Returned (Both) 


Mne- Octal 
monic Offset 


A nonzero value does not cause the tape to be rewound; 

the next record is read (it must be a label), and the tape is 
backspaced one record. When you are searching a tape for spe- 
cific files to read, the normal action is to execute this directive 
with a value of zero first. If the file is one to be read, open 
the file requesting no rewind, process the file, and close it to 
position the tape at the EOF. If the file is not one to be read, 
space the tape forward to the next EOF. (You can do this in 
MACRO with the .SPEC directive.) Then issue the DIRFQ call 
with a nonzero value in the word beginning at FIRQB+FQFIL, 
and continue the process. 


This word must be set to 177777 for the special magnetic tape 
lookup operation. 


The device name as two ASCII characters. The device must be 
a magnetic tape drive. 


The device unit number, in binary. A nonzero value in 
FIRQB+FQDEVN+1 indicates an explicit device unit num- 
ber. A zero value in FIRQB+FQDEVN+1 indicates no unit 
number. 


Octal Mne- 
Offset monic 


JI 11 current job no. * FQJOB 


(as passed) FQFIL 


f 


file name in RAD50 format FQNAM1 


(2 words) 
FQEXT 
FQSIZ 
FQNAM2 
date of last access FQMODE 
date of creation FQFLAG 
| | FQPFLG 
FQDEV 


(as passed) 


FQDEVN 


ile clustersize (disk only) FQCLUS 


USTAT byte number entries ret. FQNENT 


FIRQB+FQJOB 
FIRQB+FQPPN 
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The current job number times two. 


The PPN of the file. The project number is in the high byte 
(FIRQB+FQPPN+1) and the programmer number is in the low 
byte (FIRQB+FQPPN). 


FIRQB+FQNAM1 
FIRQB+FQEXT 
FIRQB+FQSIZ 


FIRQB+FQNAM2 
FIRQB+FQNAM2+1 
FIRQB+FQMODE 


FIRQB+FQFLAG 
FIRQB+FQPFLG 


FIRQB+FQCLUS 
FIRQB+FQNENT 
FIRQB+FQNENT+1 


Errors 


The file name; two words in RAD50 format. 
The file type; one word in RAD50 format. 


The LSB of the file size, in 512-byte blocks. This word is combined 
with the byte at FIRQB+21 to form a 24-bit value giving the file’s 
size. 


The protection code of the file. 

The MSB of the file’s size in 512-byte blocks (see FIRQB+FQSIZ). 
The date the file was last accessed, in system internal format: 
[(year/ 1970) * 1000.] + day-within-year 


See the .DATE directive for a discussion of the system internal 
format for dates. 


The date the file was created, in system internal format. 


The time that the file was created, in system internal format: 
minutes before midnight, where midnight = 1440. (See the .DATE 
directive for a discussion of the system internal format for time.) 


The file cluster size for disk devices. It is not used for tape. 
Number of entries returned: 8 for disk; 6 for tape. 


Internal flag information (disk only): 
Bit Meaning When Set 


File is placed 

Some job has write access now 

File is open in update mode 

File is contiguous; no extend allowed 


No delete or rename allowed 


NI oO fF ®©® WN FE 


File is marked for deletion 


DEVNFS The device specified is not a file-structured device. 


NOSUCH Either account (PPN) does not exist on the device specified, or no more files 
exist on the account (the index number is greater than the number of files 
on the account). Or, for the special magnetic tape lookup, no more files exist 
on the tape. 


XXXXX Other errors are device-dependent. See Appendix A for a full list of errors. 


Example 


The following code searches the disk directory to examine files for user [2,101]: 


LOOP : MOVB 
CLR 
MOV 
CLR 
CLR 
CALFIP 


#DIRFQ, FIRQB+FQFUN ;SET FUNCTION CODE 

FTIRQOB+FOFIL 

#<2.*400+101.>,FIRQB+FQPPN ;SET PROJ.,PROG.NO. 
FTROB+FQDEV ; SEARCH SYSTEM DISK 
FIRQB+FQDEVN 


(Error processing, examine file name, process file) 


INCB 
JMP 


FIRQB+FQFIL ; INCREMENT INDEX 
LOOP ;GO BACK FOR NEXT ROUND 
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3.5.9 DLNFQ (Delete a File) 


Form 
MOVB #DLNFQ, FIRQB+FQFUN 


(Define file to be deleted in FIRQB) 


CALFIP 


Function 


The DLNFQ function of CALFIP deletes a file from disk or DECtape. The moni- 
tor’s internal data on the location of the file are destroyed, and the file’s space on 
the device is made available for general use. 


Privileges Required 


DEVICE to delete a DECtape file if the referenced device is restricted. You need 
write access (by protection code, GWRITE, WWRITE, and/or SYSIO) to delete 

a disk file. Note that files marked nondeletable (using SET FILE/NODELETE) 
cannot be deleted regardless of the caller’s privileges. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


file name in RAD50 format 


1 


FQFUN 3 


6 FQPPN 


110 FONAM1 


(2 words) 


[iin 
[inn 


12 


14 FQEXT 


30 FQDEV 


32 FQDEVN 
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FIRQB+FQFUN The function code DLNFQ (octal value = 6). 


FIRQB+FQPPN The PPN of the file to deleted. The project number is in the high 
byte (FIRQB+FQPPN+1), and the programmer number is in the 
low byte (FIRQB+FQPPN). A value of zero defaults to the PPN 


under which the calling program is running. 


FIRQB+FQNAM1 The name of the file to be deleted, as two words of RAD50 data. 
FIRQB+FQEXT The file type, as one word of RAD50 data. 
FIRQB+FQDEV The name of the device containing the file to be deleted, as two 


ASCII characters; it must be a disk or DECtape device. A value of 
zero in this word indicates the public disk structure (_SY:). 


FIRQB+FQDEVN The device unit number, in binary. A nonzero value in FQDEVN+1 
, indicates an explicit device unit number. A zero value in 
FQDEVN+1 indicates no unit number. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the DLNFQ function of 
CALFIP does not return any meaningful data. 


Errors 


NOSUCH The file specified in the data passed cannot be found. 


PRVIOL Protection violation. An attempt was made to delete a file that is either 
write-protected against the cailer or marked for no delete. 


Example 


The following code deletes the file MYFIL.LST from the user’s account on the 
public structure. Assume that the FIRQB has been filled with zeros previously: 


MOVB #DLNFQ, FIRQB+FOFUN 

MOV #°*RMYF, FIRQB+FQNAM1 ;SET FILE NAME 
MOV #*RILE, FIRQB+FQNAM1+2 ; AND TYPE 

MOV #*RLST, FIRQB+FQEXT ;TO "MYFILE.LST" 
CALFIP 
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3.5.10 ERRFQ (Return Error Message Text) 


Form/Example 


MOVB #ERRFQ, FIRQB+FOQFUN 
MOVB #ERR, FIRQB+FQERNO 
Function 


The ERRFQ subfunction of CALFIP returns error message text from the system 
error message file or from the default error message file if an error message file 
is not currently installed. The text is associated with the value of the error code 
passed as byte 4 of the FIRQB. This call returns the full RSTS/E error message 
text associated with errors returned in byte 0 of the FIRQB on all the monitor 
directives. 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal | Octal Mne- 
monic Offset | Offset monic 


ERRFQ (= 16) JIT | 


LIITIITTTI ITI 


1 


FQFUN 3 


5 4 FQERNO 


7 


11 


LIIIIIIIIT II TT 


13 PIII IIIT TT I 


LTITITIIITIT ITT TT | 14 


15 


LILITH 
PIII TIT T TT I 


17 
21 


23 


| LIIIIIIIITI IIIT TT TTT 


25 


LIIIIIIIII IIT TTT 


27 


ITLTTITITT ITT IIT TT 


31 


LIITETIIII TIT T TT IT Te 
LIIIIIITIT IIT ITT TTT I 


33 
35 


LIITIIIIITI ITT TTT TT TI 
LIIIIIIIITI ITT TTT 


37 


FIRQB+FQFUN The function code ERRFQ (octal value = 16). 


FIRQB+FQERNO The error code value (in binary) for which the corresponding error 
message text is to be returned. 
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Errors _ - | 
The ERRFQ subfunction of CALFIP does not return any errors. 


Data Returned 


FIRQB | a 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 ELT LELTLLALALALALTAL 0 
5 4 FQFIL 
7 6 
1 10 
error message-padded with nulls 
13 12 
15 to 28 characters (ASCII format) | 14 
17 16 
21 20 
23 22 
25 24 
27 26 
31 30 
33 32 
35 34 
37 36 
FIRQB+FQJOB The current job number times two. 
FIRQB+3 If the job is attached, two times the currently attached keyboard 


number. If the job is detached, the one’s complement of two 
times the currently detached keyboard number. For example, if 
the keyboard number is 5, the value in FIRQB+3 is: 12 for an 
attached job and 365 (377-12) for a detached job. 


FIRQB+FQFIL The error message text begins in this byte. The text is padded 
with zeros to 28 characters, if necessary. 
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3.9.11 


LOKFQ (Disk File/Wildcard Lookup) 


Form — 
MOVB #LOKFQ, FIRQB+FQFUN 


(Set up FIRQB to define file/wildcard) 


CALFIP 


Function 
The LOKFQ subfunction of CALFIP does one of two actions: 


e Looks for a file on disk by name and returns directory information (date of 
creation, and so forth) 


e Performs a wildcard file search 


For example, with a file name and type in the FIRQB of *.TXT it searches an 
account for a file with any file name and a type of .TXT. By incrementing an 
index and reexecuting LOKFQ, you can search through an entire directory for all 
such files. 


NOTE 


For disk directory lookup on a PPN other than that of the caller, 
LOKF®Q returns only files to which the caller has read or execute 
access. 


Privileges Required 


DEVICE to perform a disk directory lookup on the caller’s account if the refer- 
enced device is restricted. You need read or execute access (by protection code, 
GREAD, or WREAD) to perform a disk directory lookup on another account. 
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Data Passed — Disk Directory Lookup 


FIRQB 
Mne- Octal Octal Mnhne- 
monic Offset Offset monic 


1 VETTEL ATAI TTL AESAG 7 0 
FQFUN 3 | LOKFQ (= 22) | PALA A TAT Ea | 2 
| popcnunior —[ poaanmeramier| 6 FaPen 
11 | file name _ ;} 10 FQNAM1 
in RAD50 format 
13 (2 words) 12 
15 file type in RAD50 format (1 word) | 14 FQEXT 
31 | device name (disk) (2 ASCII characters) 30 FQDEV 
33 <>0, device no. real 32 FQDEVN 
FIRQB+FQFUN The function code LOKFQ (octal value = 22). 
FIRQB+FQFIL The word beginning at this location must be set to 177777 (octal) 
to indicate the "disk directory lookup by file name" option of 
LOKFQ. 
FIRQB+FQPPN The PPN for the file to be looked up. A value of zero for this word 
defaults to the PPN under which the calling program is running. 
FIRQB+FQNAM1 The file name to be looked up; two words in RAD50 format. 
FIRQB+FQEXT The file type of the file to be looked up; one word in RAD50 format. 
FIRQB+FQDEV The device name (must be disk), as two ASCII characters. If both 
bytes are zero, the public disk structure (_SY:) is used. 
FIRQB+FQDEVN The disk device unit number is passed here in binary. A nonzero 


value in FQDEVN+1 indicates an explicit device unit number. A 
zero value in FQDEVN+1 indicates the system default. 
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Data Returned — Disk Directory Lookup by File Name 


Mne- Octal 
monic Offset 


. . 
5 | same as data passed (177777 octal) 4 FQFIL 
11 file name in RAD50 format 10 FQNAM1 
13 (2 words) 12 
15 file type in RAD50 format (1 word) 14 FQEXT 
17 LSB of file length in 512-byte blocks 116 FQSIZ 
21 MSB of file length 20 FQNAM2 
23 date of last access 22 FQMODE 
25 date of creation 24 FQFLAG 
27 time of creation 26 FQPFLG 
31 device name (2 ASCII characters) 30 FQDEV 
37 file identification index 36 FQNENT 
FIRQB+FQJOB The current job number times two. 
FIRQB+FQFIL The word at this location is the same as the data passed, in this 
case, 177777 (octal). 
FIRQB+FQPPN The PPN of the file (same as data passed). 
FIRQB+FQNAM1 The file name; two words in RAD50 format (same as data passed). 
FIRQB+FQEXT The file type; one word in RAD50 format (same as data passed). 
FIRQB+FQSIZ The LSB of the file’s size in 512-byte blocks. This word is com- 
bined with the byte at FIRQB+21 to form a 24-bit field giving the 
file size. 
FIRQB+FQNAM2 The file’s protection code, in binary, is returned in this byte. 
FIRQB+21 The MSB of the file size in 512-byte blocks. It is combined with 
the word at FIRQB+FQSIZ to form a 24-bit field giving the file 
size. 
FIRQB+FQMODE The date the file was last accessed, in system internal format: 
[(year - 1970) * 1000.] + day-within-year. 
See the .DATE directive for a discussion of the system internal 
format for dates. 
FIRQB+FQFLAG The date the file was created, in system internal format (see 
FIRQB+FQMODE). 
FIRQB+FQPFLG The time the file was created, in system internal format: minutes 
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FIRQB 
Octal Mne- 
Offset monic 


until midnight, with 1440 equal to midnight. 


FIRQB+FQDEV The device name, as two ASCII characters. Always a specific 


name, even if zero was passed here. 


FIRQB+FQDEVN The device unit number, in binary. A specific number is always 
returned here; FIRQB+FQDEVN+1 is always nonzero. 

FIRQB+FQCLUS The file cluster size is returned in this word. 

FIRQB+FQNENT The file identification index is returned in this word. You can 


use the file identification index instead of the file name to open 

a file on disk with the OPNFQ subfunction of CALFIP. To do so, 
specify an explicit device name at FIRQB+FQDEYV, a device unit 
number at FIRQB+FQDEVN, an explicit PPN at FIRQB+FQPPN, 
a zero word at FIRQB+FQNAM1, and the file identification index 
at FIRQB+FQNAM1+2. (The file identification index is used by 
utilities that access software subroutines in the RMS libraries, for 
example.) 

Note that there is no performance gain in using the file identifica- 
tion index instead of the file name. The file identification index is 
provided for compatibility with RSX. Furthermore, the file identi- 
fication index is changed when the REORDR utility is run on the 
directory (see the RSTS/E System Manager’s Guide). 


Errors 


BADNAM The file name in bytes FIRQB+FQNAMI1 through FIRQB+13 is missing or 


invalid. 


NOSUCH The device specified at FIRQB+FQDEV is not disk, or the file specified does 
not exist on the specified disk. This error also occurs when a user does not 
have read or execute access to the specified file. 


Example 

The following code looks for the file MATRIX.DAT on the system disk: 
CALL CLRFQB ;CLEAR FIRQB 

MOV #LOKFQ, FIRQB+FQFUN ;SET FUNCTION CODE 
MOV #177777, FF IRQBt+FQFIL ;FILENAME LOOKUP 
CLR FIRQB+FQPPN ;CALLER’S ACCOUNT 
MOV #°RMAT, FIRQB+FQNAM1 ;SET FILENAME 

MOV #°RRIX, FIRQB+FQNAM1+2 ;AND TYPE 

MOV #°RDAT, FIRQB+FQEXT ;TO "MATRIX.DAT" 
CLR - FIRQB+FQDEV ; SYSTEM DISK 

CLR F IRQB+FQDEVN ; DEVICE 

CALFIP 


See Programming Hints for information on the CLRFQB routine. 
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Data Passed — Disk Wildcard Directory Lookup 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


terra ez tn 
[dr nce sath ort were 
[rest namver [earner umber 


wildcard file name 
specification in RAD50 format 
(2 words) 


wildcard file type in RAD50 format (1 word) 


1 


FQFUN 3 


5 4 FQFIL 


7 6 FQPPN 


11 10 FQNAM1 


13 
15 14 FQEXT 


17 


21 
23 22 FQMODE 


25 


LTVAATITLALT TT ALT ALA AY 


27 


31 device name (disk) (2 ASCII characters) 


30 FQDEV 
33 


<>0, device no. real device unit number 32 FQDEVN 


35 PINAL ATATALEAALE TAA 


37 PIITAITITTIT ITT TT I 


FIRQB+FQFUN The function code LOKFQ (octal value = 22). 


FIRQB+FQFIL An index number specifying the occurrence of the file name 
meeting the wildcard specifications. A value of zero in this word 
causes the monitor to search for the first file name in the directory 
that meets the specification. A value of one causes the monitor to 
search for the second file name, and so forth. 


FIRQB+FQPPN The PPN of the account whose directory of disk files is to be 


searched. 


FIRQB+FQNAM1 The wildcard file name; as two words in RAD50 format. Either 
an asterisk (*) character can replace the entire file name, or a 
question mark (?) character can replace any character in the 
file name. For example, a file name of FILE?? would cause the 
monitor to search the directory for any file name beginning with 
the characters FILE. An * character indicates that the file name 
does not matter in the search. 


FIRQB+FQEXT The wildcard file type; as one word in RAD50 format. An * 
character can replace the entire file type, or a ? character can 
replace any character in the file type. For example, a file type of 
BA? causes the monitor to search the directory for any file type 
beginning with the characters BA. An * character indicates that 
the file type does not matter in the search. 


FIRQB+FQMODE If bit 14 is set, LOKFQ returns information about marked-for- 
delete files. 
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FIRQB+FQDEV The name of the device to be searched (must be disk). A value of 
0 in this word indicates the public disk structure (_SY:). 


FIRQB+FQDEVN The device unit number in binary. A nonzero value in 
FIRQB+FQDEVN+1 indicates an explicit device unit number. 
A zero value in FIRQB+FQDEVN+1 indicates the system default. 


Data Returned — Disk Wildcard Directory Lookup 


FIRQB 
Mne- Octal | Octal Mne- 
monic Offset | Offset monic 
1 | 0 
5 | (as passed) 4 FQFIL 
11 | file name in RAD50 format | 10 FQNAM1 
13 | (2 words) 12 
15 file type in RAD50 format (1 word) 14 FQEXT 
17 LSB of file length in 512-byte blocks 16 FQSIZ 
21 MSB of file length protection code | 20 FQNAM2 
23 | date of last access (disk only) 22 FQMODE 
31 30 FQDEV 
(as passed) 
33 32 FQDEVN 
35 file clustersize (disk only) 34 FQCLUS 
a7 | __ustat byt 36 FONENT 

FIRQB+FQJOB The current job number times two. 

FIRQB+FQPPN The PPN of the file (same as data passed). 

FIRQB+FQNAM1 The actual file name of a file meeting the wildcard specification in 
the data passed; two words in RAD50 format. 

FIRQB+FQEXT The actual file type of a file meeting the wildcard specification in 
the data passed; one word in RAD50 format. 

FIRQB+FQSIZ The LSB of the file’s size in 512-byte blocks. This word is com- 
bined with the byte at FIRQB+21 to form a 24-bit field giving the 
file’s size. 

FIRQB+FQNAM2 The file’s protection code, in binary, is returned in this byte. 

FIRQB+21 The MSB of the file’s size in 512-byte blocks. The byte is combined 
with the word at FIRQB+FQSIZ to give the file’s size. 

FIRQB+FQMODE The date the file was last accessed, in system internal format: 


[(year - 1970) * 1000.] + day-within-year. 


See the .DATE directive for a discussion of the system internal 
format for dates. 
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FIRQB+FQFLAG The date the file was created, in system internal format (see 


FIRQB+FQMODE). 

FIRQB+FQPFLG The time the file was created, in system internal format: minutes 
until midnight, with 1440 equal to midnight. 

FIRQB+FQDEV The device name, as two ASCII characters. Always a specific 
name, even if zero was passed here. 

FIRQB+FQDEVN The device unit number, in binary. A specific number is always 
returned here; FIRQB+FQDEVN+1 is always nonzero. 

FIRQB+FQCLUS The file cluster size is returned in this word. 


FIRQB+FQNENT+1  ~—Internal flag information: 
Bit Meaning When Set 


File is placed 

Some job has write access now 

File is open in update mode 

File is contiguous; no extend allowed 


No delete or rename allowed 


qY oa fF WO DN & 


File is marked for deletion 


Errors 


BADNAM No file specification appears at FIRQB+FQNAM1 or the file name is invalid. 
NOSUCH Either the device specified at FIRQB+FQDEV and FIRQB+FQDEVN is 


not a disk, or no match exists for the occurrence specified in the word at 


FIRQB+FQFIL. 
PAKLCK The disk is restricted and the caller does not have DEVICE privilege. 
Example 


The following code asks the monitor to search the directory for account [2,130] for 
the first occurrence of a file specification beginning with the letter X: 


CALL CLRFOB ;MAKE SURE FIRQB 

CALL CLRXRB ;AND XRB ARE CLEAR 

MOV #F ILNAM, XRB+XRLOC ;POINT TO FILE NAME 

MOV #NAMSIZ,XRB+XRLEN ;SET ITS LENGTH 

MOV #NAMSIZ,XRB+XRBC ;AND AGAIN 

.FSS ;CONVERT TO FIRQB FORMAT 
MOVB #LOKFQ, FIRQB+FQFUN ;SET FUNCTION CODE 

CALFIP | 

FILNAM: .ASCII "[2,130]X2???72?.*" ;STRING FOR .FSS TO CONVERT 
NAMSIZ = .-FILNAM ;AND ITS LENGTH 

See Programming Hints for information about the CLRFQB and CLRXRB rov- 
tines. 
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3.5.12 OPNFQ (Open a File/Device on a Channel) 


Form 
MOVB #OPNFQ, FIRQB+FQFUN 


(Set parameters appropriate to file or device) 


CALF IP 


Function 


The OPNFQ function has the same effect as an OPEN FOR INPUT statement 
in BASIC-PLUS; it opens a device or existing file on a channel. Parameters 
defining the device, file name and type, protection code, and mode are passed to 
the monitor in the FIRQB. If a file name is given in the FIRQB, a file-structured 
open for input is performed. If no file name is given, a non-file-structured open 
for input is performed. The RSTS/E Programming Manual describes file- and 
non-file-structured OPEN FOR INPUT statement and the actions taken for the 
mode parameter (MODE modifier in BASIC-PLUS) for each device. 


If the device being opened is an outbound LAT keyboard, OPNFQ initiates a 
connection to the terminal server if no such connection already exists. 


NOTE 


Privileges are required to open a disk for non-file-structured processing. 
Whenever you use a disk as a non-file structured device, be aware that 
all RSTS/E data structures you access are subject to change at any 
time. The same applies if you open a UFD as a file. 

Privileges Required 


No privileges are required to open the caller’s UFD for read-only access. 
Privileges are needed to perform the following: 


e GREAD to open the UFD of any other account in the caller’s group for 
read-only access 


e WREAD to open the UFD of any account outside the caller’s group for read- 
only access 


e DEVICE to open a restricted device 


: e Read access (protection code, GREAD, or WREAD) to open a disk file for 
read-only access 


e Write access (protection code, GWRITE, WWRITE, and/or SYSIO) to open a 
disk file for write access 


e EXQTA to specify detach on close option on a pseudo keyboard 

e TUNE to select data caching mode on open 

e RDNES to gain non-file-structured read access to a disk 

e SYSMOD to gain non-file-structured write access to a mounted disk 


e WRITNFS to gain non-file-structured write access to a disk, or to gain write 
access to a UFD 
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Data Passed 


Mne— Octal! 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


. . 
11 file name in RAD50 format 10 FQONAM1 
13 (2 words) 12 
15 file type in RAD50 format (1 word) 14 FQEXT 
17 receive buffer size for DMC11/DMR11 16 FQSIZ 
31 device name (2 ASCII characters) 30 FQDEV 
33 <>0, unit no. real 32 FQDEVN 
35 no. rec. bfrs. to allocate for DMC11/DMR11 34 FQCLUS 
37 LIIIITTAIT ITT TT 36 

FIRQB+FQFUN The function code OPNFQ (octal value = 2). 

FIRQB+FQFIL Channel number times two; defines the channel on which the file 
is to be opened. 

FIRQB+FQPPN The PPN of the file to be opened. The project number is in the 
high byte (FQPPN+1), and the programmer number in the low 
byte (FQPPN). A value of zero defaults to the PPN under which 
the calling program is running. (Zero for non-file-structured open.) 

FIRQB+FQNAM1 The file name to be opened; two words of RAD50 data. May also 
be specified as a zero word followed by the file identification index 
(see LOKFQ). (Must be two zero words for a non-file-structured 
open.) 

FIRQB+FQEXT The file type; one word of RAD50 data. (Must be zero for a 
non-file-structured open.) 

FIRQB+FQSIZ This parameter has the same function as the FILESIZE option 
in BASIC-PLUS. It is only used for the DMC11/DMRI11, where it 
specifies the receive buffer size. You can specify a value between 1 
and 632 (1170 octal). See the RSTS/E Programming Manual for 
more information. 

FIRQB+FQMODE The mode with which the file is to be opened; values and actions 
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taken are as described for the MODE modifier in OPEN FOR 
INPUT and non-file-structured OPEN statements for various 
devices, as described in the RSTS/E Programming Manual. If 
you use a mode value at all, you must set bit 15 of this word to 1. 


FIRQB+FQDEV The device name is passed here as two ASCII characters. A value 
of zero indicates "SY", public disk. 


FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in the high byte of this word (FIRQB+FQDEVN+1) indicates an 
explicit device unit number. A zero value in FIRQB+FQDEVN+1 
indicates no unit number. 


FIRQB+FQCLUS | This parameter has the same function as the CLUSTERSIZE 
option in BASIC-PLUS. For OPNFQ, it is used only for the 
DMC11/DMR11, where it specifies the number of receive buffers 
to allocate. You can specify a value between 1 and 127, but val- 
ues greater than four are not recommended. See the RSTS/E 
Programming Manual for more information. 


Data Returned 


FIRQB | 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
‘(mmm | 
7 reaiees number spoararinet auinbet 6 FQPPN 
11 | “file name in RAD50 fecal. | 10 FQNAMT1 
13 (2 words) 12 


NOTE 


For nondisk devices, the relevant information returned with the 
OPNF@Q subfunction is in the two words at FIRQB+FQBUFL and 
FIRQB+FQFLAG. All other words are returned as passed. 


FIRQB+FQJOB The current job number times two. 
FIRQB+FQFIL Channel number times two; defines the channel on which the file 
is open. 
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FIRQB+FQSIZM For large disk files (greater than 65,535 blocks), this byte contains 
the MSB of the file’s size in 512-byte blocks. This byte is combined 
with the word at FIRQB+FQSIZ to form a 24-bit field giving the 


file size. 

FIRQB+FQPPN The PPN under which the file is open. An actual PPN is returned 
here even if this word was passed as zero. 

FIRQB+FQNAM1 The file name; two words of RAD50 data. 

FIRQB+FQEXT The file type; one word of RAD50 data. 

FIRQB+FQBUFL Reasonable buffer size for this device, in bytes. If you are doing 


device-independent I/O (that is, if you do not want to keep track 
of which device is being opened and perform specific opens, reads, 
and writes, depending on the device), this value is the monitor’s 
best guess for a buffer size to use in subsequent reads and writes 
on the opened channel. (See the .READ and .WRITE directives.) 


FIRQB+FQFLAG Description of the device just opened. The low byte contains the 
device’s handler index. There is one unique handler index for all 
device types. The high byte contains a set of status flags to allow 
for device-independent I/O routines. 


DDNFS 
DDRLO 
DDWLO 
FLGPOS 
FLGMOD 
FLGFRC 
FLGKB 
“| | 


1514 13 12 1110 9 8 7 0 
device-type flags device handler index 


High Byte — Device-Type Flags 


The bits in the high byte of the flags word are set to indicate the type of file or device just 
opened. 


FLGRND =1 The device or file is random-access. 


= 0 The device or file is sequential. 
FLGKB aed The file or device is a terminal-type file or 
device (or is generically a terminal). 
= 0 The file or device is not a terminal-type file or 
device. 


FLGFRC =1 The file or device is byte-oriented. That is, 
the .READ and .WRITE directives handle 
data in byte units. 

= 0 The file or device is block-oriented. The 
-READ and .WRITE directives handle data in 
block units. 
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FLGMOD 


FLGPOS 


Low Byte — Device Handler Index 


=] 


ae | 


= 0 


The file or device accepts modifiers in .READ 
and .WRITE directives. 


The file or device does not accept modifiers in 
-READ and .WRITE directives. 


The file or device keeps track of its horizon- 
tal position and expands characters such as 
TAB into whatever is appropriate for the 
file or device. You can determine the cur- 
rent horizontal position with the .POSTN 
directive. 


The file or device does not keep track of its 
horizontal position. 


The file or device has been write-locked (with 
the protection code or mode value in the open) 
or is generically a read-only device. 


The file or device is not write-locked. 


The file or device has been read-locked (with 
the protection code in the open) or is generi- 
cally a write-only device. 


The file or device is not read-locked. 


The file or device is non-file-structured (or is 
generically not a file-structured device). 


The file or device is file-structured. 


Bits 0-7 of the flags word contain a handler index that indicates the generic kind of device. 
The currently defined values follow. 


Octal 
Value 


0 
2 


Symbol 


DSKHND 
TTYHND 
DTAHND 
LPTHND 
PTRHND 
PTPHND 
CDRHND 
MTAHND 
PKBHND 
RXDHND 
RJEHND 
NULHND 
DMCHND 


KMCHND 
IBMHND 

DMPHND 
ETHHND 


Meaning 


All disks 

All terminals 
DECtape 

All line printers 
Paper tape reader 
Paper tape punch 
Card reader 
Magnetic tape 
Pseudo keyboards 
Flexible diskettes 
2780 remote job entry 
The null device 


The DMC1I/DMR11 DDCMP inter- 


face 

Reserved 

KMC11 

IBM interconnect 
DMP11/DMVI11 device 


Ethernet device 
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FIRQB+FQPFLG The file cluster size, modulo 256. That is, a file cluster size of 256 


is indicated a zero. 


FIRQB+FQPROT The protection code of the file. 
FIRQB+FQDEV The device name; two ASCII characters. (For disk, the actual 


device name is returned, even if a zero word was passed in this 
word.) 


FIRQB+FQDEVN The device unit number. (For disk devices, the actual unit number 


FIRQB+33 


is returned here, even if FIRQB+FQDEVN+1 was passed as zero.) 


For a file-structured open, this byte contains two relevant bits: 
Bit 0 = 0 The device is in the public structure 


Bit 0 = 1 The device is a private disk 
Bit 1 = 0 A specific device was not specified 
Bit l=1 A specific device was specified 


These bits are meaningless for a non-file-structured open. 


FIRQB+FQCLUS The file identification index of this file. This word is significant 


Errors 


NOBUFS 
NOTCLS 


PRVIOL 


Example 


mainly in that it can be used in place of the file name in subse- 
quent opens of the file on disk. You can open the file with the 
OPNF@Q subfunction by using an explicit PPN in FIRQB+FQPPN, 
a zero word in FIRQB+FQNAM1, and the file identification index 
in FIRQB+FQNAM1+2. 


Note that there is no performance gain in using the file identifica- 
tion index instead of the file name. The file identification index is 
provided for compatibility with RSX. Furthermore, the file identi- 
fication index is changed when the REORDR utility is run on the 
directory (see the RSTS/E System Manager’s Guide). 


No buffers are available to initiate the connection to the terminal server. 


The specified channel is already open. It must be closed before it can be 
opened again. 


You do not have the necessary privilege and you tried to: 


e Open a disk for non-file-structured access. 


e Open a device that the system manager has restricted to users with 
DEVICE privilege. 


All other possible errors are device-dependent. See Appendix A for a full list 
of errors. 


The following MACRO code sets up the FIRQB for the OPNFQ function. A 
non-file-structured open of magnetic tape unit 2 is done on channel 3: 


MAG: 


-ASCII /MT/ 


CALL CLRFOB ;CLEAR FIRQB 


MOVB #OPNFQ, FIRQB+FQFUN ;SET FUNCTION CODE 

MOVB #3*2,F IRQBt+FQFIL ;SET CHANNEL = 3 

MOV MAG, FIRQB+FQDEV ;SET DEVICE = MT 

MOVB #377,F IRQB+FQDEVN+1 ;SET FLAG DEVICE NO. EXPLICIT 
MOVB #2, FIRQB+FQDEVN ;SET DEVICE NO. = 2 

CALFIP 


See Programming Hints for information on the CLRFQB routine. 
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3.5.13 RENFQ (Rename a File) 


Form 


MOVB #RENFQ, FIRQB+FQFUN 
(Define file to be renamed and new name in FIRQB) 


CALFIP 


Function 


The RENFQ function renames an existing file on disk or DECtape and, if re- 
quested, deletes any existing file with the new name. 


Privileges Required 


DEVICE is required if the device is restricted. Create/rename access (GWRITE, 
WWRITE, and/or SYSIO) to rename a disk file outside the caller’s account. 
SYSIO to set the privilege bit (bit 7 in FQPROT). 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 LETETATALEL IE TIA TALE Ee 0 
FQFUN 3 RENFQ (= 10) | ELETLLELL ST 2 
5 LITTITIITTI TIT TT TT ; 4 
11 | file name 10 FQNAM1 
in RADS50 format 
13 (2 words 12 
15 file type in RAD50 format (1 word 14 FQEXT 
17 -1 to delete existing file (disk only) 16 FQSIZ 
21 new file name 20 FQNAM2 
| in RAD50 format 
23 (2 words) 22 
25 new file type in RAD50 format (1 word) 24 FQFLAG 
rapRot 27| file protection | -0lfnochange | 26 FOPFLG 
31 device name (disk) (2 ASCII characters) 30 FQDEV 
35 | EIEILALE ALANS EELALS Fl 34 
37 | LITIIIIITII TTT TTI 36 
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FIRQB+FQFUN The function code RENFQ (octal value = 10). 


FIRQB+FQPPN The PPN of the existing file to be renamed. The project number is 
in the high byte (FIRQB+FQPPN+1), and the programmer number 
is in the low byte (FIRQB+FQPPN). A value of zero defaults to the 
PPN under which the calling program is running. 


FIRQB+FQNAM1 The old (existing) name for the file; two words of RAD50 data. 
FIRQB+FQEXT The old (existing) type for the file; one word of RAD50 data. 
FIRQB+FQSIZ This word is set to -1 to indicate that any existing file on the 


specified device with the new name is to be deleted. If any other 
value is given here and a file already exists with the new name, 
the RENFQ function will return an error. 


FIRQB+FQNAM2 The new file name and type; three words of RAD50 data. You 
can use RENFQ to change the protection code on a file by setting 
FQPROT and making these three words the same as the three 
words beginning at FIRQB+FQNAMI1. 


FIRQB+FQPROT The new protection code for the file, if any, is specified in 
this byte. To retain the old protection code, this entire word 
(FIRQB+FQPFLG and FIRQB+FQPROT) must be zero. If the 
word is nonzero, the high byte will be used as the new protection 
code. 


FIRQB+FQDEV The device name is passed here as two ASCII characters. It 
| must be a disk or DECtape device. A value of zero in this word 
indicates the public disk structure (_SY:). 


FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in FIRQB+FQDEVN+1 indicates an explicit device unit number. 
A zero value in FIRQB+FQDEVN+1 indicates the system default. 

Data Returned 

Other than a possible error in byte 0 of the FIRQB, the RENFQ function of 

CALFIP does not return any meaningful data. 


Errors 


FIEXST The new file name specified already exists. 
NOSUCH The old file specified cannot be found. 


Example 


The following code renames the file OLDNAM.TXT to NEWNAM. TXT on the 
public disk structure under the caller’s account. FQSIZ is set to -1, so any 
existing file named NEWNAM.TXT is deleted: 


CALL CLRFQB ;CLEAR FIRQB 

MOVB #RENFQ, FIRQB+FOQFUN ;SET FUNCTION CODE 
MOV #*ROLD, FIRQB+FQNAM1 ;SET OLD FILE NAME 
MOV #“RNAM, FIRQB+FQNAM1+2 ; AND TYPE 

MOV #“RTXT, FIRQB+FQEXT 7;TO "OLDNAM. TXT" 

MOV #-1,F IRQB+FQOSIZ ;DELETE EXISTING FILE 
MOV #“RNEW, FIRQB+FQNAM2 ;SET NEW FILE NAME 
MOV #“RNAM, FIRQB+FQNAM2+2 7; AND TYPE 

MOV #°*RTXT, FIRQB+FQNAM2+4 ;TO "NEWNAM. TXT" 
CALFIP 


See Programming Hints for information about the CLRFQB routine. 
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3.5.14 RSTFQ (Reset a Channel) 


Form 
MOVB #RSTFQ, FIRQOB+FOFUN 


(Define channel to be reset) 
CALF IP 


Function 


The RSTFQ function closes a channel, all channels, or all channels except one 
without performing any of the normal clean-up operations. For example, no 
trailer tape is written to paper tape punch; no form feed is given on the line 
printer; and no trailer labels are written to magnetic tape. This function is useful 
as a backup to a normal close operation. If a normal close fails, RSTFQ will close 
the channel regardless. You can also use RSTFQ to closes a channel on which a 
tentative file is open if you do not want to make the file permanent. The RSTFQ 
directive functions the same as a CLOSE statement with a negative channel 
number in BASIC-PLUS. See the RSTS/E Programming Manual for description 
of tentative files. | 


Privileges Required 


None 
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Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 TAIT EITIT IITA TT Tt 0 

| ) 
FIRQB+FQFUN The function code RSTFQ (octal value = 20). 
FIRQB+FQFIL The value is set as follows: 


e To reset one channel, set FIRQB+FQFIL to the channel 
number to reset times two 


e To reset all channels, set FIRQB+FQFIL to zero 


¢ To reset all but one channel, set FIRQB+FQFIL to -(channel 
number times two); that is, the negative of two times the 
channel number to remain open 


Data Returned 
The RSTFQ function does not return any meaningful data. 
Errors 


No errors are possible with the RSTFQ function. If the channel or channels 
specified are not open, the call simply returns without error. 


Example 


The following code resets all channels currently open for the job, except channel 2: 


CALL CLRFQB ;CLEAR FIRQB 

MOVB #RSTFQ, FIRQB+FQFUN ; SET FUNCTION CODE 

MOVB #-4,F IRQB+FOFIL ;RESET ALL CHANNELS BUT 2 
CALFIP 


See Programming Hints for information about the CLRFQB routine. 
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3.5.15 UUOFQ (Hook to File Processor) 


Form 
MOVB #UUOFQ, FIRQB+FOFUN 


(Set up FIRQB for UUOFQ subfunction) 


CALF IP 


Function 


The UUOFQ subfunction of CALFIP performs the same operations as the .UUO 
directive. The same subfunctions are available, and a similar format is used 
for the data passed. The data returned is in the same format as for the .UUO 
directive. 


The data passed for the UUOFQ subfunction of CALFIP is moved down one byte 
from the .UUO subfunction format. The value UUOFQ is stored in byte 3 in the 
FIRQB, the UU.xxx code is stored in byte 4 in the FIRQB, whatever is shown in 
byte 4 for .UUO is stored in byte 5 for UUOFQ, and so forth. 


The UUOFQ subfunction of CALFIP is not recommended (although it does work), 
because values that are normally set up as whole words must be stored as a 
high-byte in location n and a low-byte in location n+1. 


For example: 


.UUO form: 


UUOFQ form: 


Privileges Required 
See the .UUO directive. 
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3.6 .CCL — Check String for CCL Command 


3-64 .CCL 


Form 
.CCL 


Function 


The .CCL directive asks the monitor to check a string (defined in the XRB) to 
see if it is a valid Concise Command Language (CCL) command. If the string is 
a valid CCL command, the monitor passes control to the appropriate run-time 
system for that CCL (as defined by the system manager), using the equivalent of 
a .RUN directive. If the directive is successful, control does not return in line. 


Control passes to the run-time system at the location specified in the PRUN word 
in the pseudovector region (Chapter 2). Data in the job’s CORCMN, XRB, FIRQB, 
and KEY areas in the low segment are passed to the run-time system because 
they are of interest to the run-time system being entered as a result of a .CCL, 
not to the caller. The file containing the program to be run as a result of the .CCL 
command is opened on channel 15, See Chapter 2 for a description of these areas 
in the PRUN word. 


If the string is not a valid CCL command, the monitor returns control to the 
caller (the run-time system or user job image that issued the .CCL directive) with 
no error. Control resumes with the instruction following the .CCL. Since control 
would not be returned here otherwise, the program does whatever housekeeping 
it deems necessary here for an unsuccessful CCL. 


The system manager defines the CCL command, an abbreviation point, the name 
of the file that is to be executed when the command is given, and an entry point 
for the program (see the RSTS/E System Manager’s Guide). 


The command can be a string from one to nine characters long. The allowed 
single-character commands are A through Z, @, $, and #. Commands that are 
longer than one character must begin with a letter; the remaining characters can 
be letters or digits. 


The abbreviation point defines how many characters must be specified before 
the command is accepted as valid. For example, if "DIRECTORY" were defined 
as a CCL command, the system manager could indicate three characters as the 
abbreviation point for the command. Then DIR, DIRE, DIREC and so forth, up 
to the full DIRECTORY, would all be interpreted by the monitor as correct CCL 
commands. (The monitor always fills in the full CCL command in CORCMN 
when it passes control to the appropriate run-time system.) When you issue a 
.CCL directive, the monitor compares the indicated string with the commands 
defined by the system manager: 


e All null (ASCII code 000) and delete (ASCII code 177) characters are ignored 
and are never passed on to the run-time system in CORCMN. 


e ASCII code 200 is ignored and is never passed on to the run-time system in 
CORCMN. 


e Leading spaces (ASCII code 040) and tabs (ASCII code 011) are ignored and 
are never passed on to the run-time system in CORCMN. 


e When not enclosed by the quote characters " (ASCII code 042) and ’ (ASCII 
code 047): 


— All tabs (ASCII code 011) are changed to spaces (ASCII code 040). 


— All control characters (ASCII codes 001 through 037, inclusive, and 
ASCII codes 201 through 237, inclusive) are ignored and never passed in 
CORCMN. 


- Adjacent spaces (ASCII code 040) are merged into a single space. 


— All lowercase alphabetics (ASCII codes 141 through 172, inclusive, and 
ASCII codes 341 through 376, inclusive) are changed into their uppercase 
equivalents (ASCII codes 101 through 132, inclusive, and ASCII codes 301 
through 336, inclusive). 


¢ When enclosed by the quote characters " (ASCII code 042) and ’ (ASCII code 
047), all characters are kept as is and passed on to the run-time system in 
CORCMN. 


Immediately following the CCL command text (for example, DIR/SI:n/DET) the 
monitor also analyzes two switches. These switches are passed on to the run-time 
system as status flags set in the XRB (see the P RUN description in Chapter 2). 
The two switches may appear in either order, but must immediately follow the 
command. Both are optional switches. 


The /SIZE switch has the format: 
[space] /SI[Z[E]]: [+t] [#]n[.] 


where n indicates the size, in K words, of the user job image that the program, 
when executed, will require. If the + sign is given, n indicates the additional 
amount of space, in K words, that the file will require over that indicated by the 
computed size or minimum size (see the description of the PF.CSZ bit in PFLAGS 
word, Chapter 2). If the + sign is omitted, then n simply indicates the size, in K 
words, at which the invoked file should run. If the # sign is given, n is assumed to 
be octal. If the period (.) is given, n is assumed to be decimal. If both are given, 
an error is returned, and if neither is given, n is assumed to be decimal. The 
value of n must be between 1 and the system-wide maximum for a user job image 
(see the SWAP MAX discussion in the RST'S/E System Installation and Update 
Guide). If you run the program with separate D-Space, /SIZE only increases the 
D-Space. Otherwise, it increases the overall program size. 


The /DETACH switch has the format: 
[space] /DET[A[C[H]]] 


This switch indicates that the invoked program should be run detached. In this 
state, channe! 0 (the terminal associated with the job) is marked as detached 
while the program is running. This switch is useful for noninteractive programs; 
it frees the terminal for other use and prevents the user from interrupting the job 
by entering a Ctrl/C. 


Remember that the monitor simply examines these switches and passes the 
information on to the run-time system. The run-time system is responsible for 
doing the appropriate processing. For more information on the CCL facility, see 
the RSTS/E Programming Manual. 


NOTE 


Do not use this directive from a user job image running under the 
RT-11 run-time system, since the lowest 512. bytes are used by RT-11 
differently from other run-time systems. Instead, use .DOCCL (see 
Chapter 7). 
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Privileges Required 


Execute access (by protection code, GREAD, or WREAD) is needed to execute a 
program for a CCL command. 


Data Passed 


XRB 
Mine- Octal Octal Mne- 
monic Offset Offset monic 
XRLEN 
XRBC 
XRLOC 
XRBLK 
(passed to 
new run-time system 
unaltered) 
XRB+XRLEN The length of the proposed CCL command string, in bytes. 
XRB+XRBC The length of the proposed CCL command string, in bytes, is also 
passed in this word. 
XRB+XRLOC The starting address of the proposed CCL command string. (See 


the section "XRB (Transfer Request Block)" in Chapter 2 for more 
information.) 


XRB+XRBLK The remaining three words are unaltered here if the string is 
indeed a CCL command and the monitor takes over and does the 
equivalent of a .RUN directive. That is, the run-time system that 
is given control as a result of this command finds the same three 
words here that the caller left. These three words are also be 
unchanged if control returns back to the caller for any reason. See 
the .RUN monitor call in this Chapter and the PRUN entry point 
in Chapter 2 for details. 


Data Returned 


No useful data is returned to the calling program. (The P.RUN description 
describes the data passed to the run-time system if the call is successful.) If the 
call is unsuccessful, the last three words of the XRB are unaltered, but the first 
four words are random. In addition, an error code is returned in the first byte of 
the FIRQB. 
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Errors 


(none) 


BADCNT 


BADSWT 
BDNERR 


LINERR 


XXXKXK 


Example 


No error is returned if the command part of the string passed was not a 
valid CCL command. The contents of CORCMN have not been altered; the 
XRB (except for the last three words) has been altered. 


The first three words of the XRB, which describe the CCL command string, 
are illegal. 


An illegal switch was given in the CCL command string. 


An illegal number was the argument to one of the switches found in the 
CCL command string. For example, the n value in the /SIZE switch was 
greater than the system-wide maximum for a user job image (see the SWAP 
MAX discussion in the RSTS/E System Installation and Update Guide). 


The indicated string is too long to be passed in CORCMN. 


Any other error returned results from the monitor’s execution of a .RUN 
directive for the program. See the .RUN directive in this chapter. 


The following example asks the monitor to check a 72-byte string beginning at 
location BUFFER to see if it is a CCL command: 


BUFFER: 


- BLKB q2s 

CALL CLRXRB ; Clear XRB 

MOV #72.,XRB+XRLEN ; Set length 

MOV #72.,XRB+XRBC ; Set length again 
MOV #BUFFER, XRB+XRLOC ; Set starting address 
~CCL 


See the section entitled "Programming Hints" for information on the CLRXRB 


routine. 
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3.7 .CHAIN — Execute Under Same RTS 
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Form 
.CHAIN 


Function 


The .CHAIN directive is the same as the .RUN directive, except that it returns an 
error if the program to be run would cause a new run-time system to be entered. 


That is, if the call succeeds, the current run-time system is entered at the PRUN 


entry point (see Chapter 2). In addition, there is no change in the user job image 
size. Otherwise, the error code NORTS is returned in byte 0 of the FIRQB. 


Use this call to bypass the special protection afforded by the compiled-file bit 

in the protection code. The run-time system can use this directive to access 

an executable file without the problem of possibly losing control (unlike .RUN, 
which can transfer control to a different run-time system). The .CHAIN directive 
reenters the run-time system so a user cannot take control of the file once it is 
open on channel 15. 


‘See the RUN directive, for Data Passed, Data Returned, and Errors. For the 


example, substitute .CHAIN for .RUN. 
NOTE 


Do not use this directive from a user job image running under the 
RT-11 run-time system. Use the RT-11 .CHAIN directive (see Chapter 
7) to transfer control to another program running under RT-11. 


Privileges Required 


Execute access (by protection code, GREAD, or WREAD) is required to execute a 
program. 


3.8 .CLEAR — Clear Keyword Bits 


Form 
.CLEAR 


Function 


Use the .CLEAR directive to clear certain bits in the keyword (KEY) location in 
the user job image. The XRB passes the bits to be cleared to the monitor. 


Privileges Required 


None 
Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


bits to be cleared are set to 1 here | QO XRLEN 
IIA AAA AA 2 
LTITITIIITIA TIAA 4 


LAAT ATALA LAAT AAT SALA 10 
LETEET ITALIA ETAT ALL 12 
FLAP EAA ETALTAD TALL TD 14 


XRB+XRLEN The bits to be cleared are set to 1 here. 


JFSPRI JDFSTM 
JFFPP 


JFPRIV 
JFSYS : 
JFNOPR 
JFBIG 
| 
15 14 13 12 11 [ae 0 


JFLOCK Clearable by any caller. Clearing JFLOCK indicates that the job wants to 
be swapped. When JFLOCK is clear, the monitor swaps the job (that is, 
the user job image) to and from disk as necessary. 


JEBIG Not clearable by any caller; masked off. That is, the corresponding bits in 
KEY cannot be cleared by the job with the .CLEAR directive. 

JFNOPR Not clearable by any caller; masked off. 

JFSYS Clearable by any caller. If the job has temporary privileges and this bit is 


cleared in a .CLEAR call, the temporary privileges are temporarily lost. 
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JFPRIV If a .CLEAR directive is issued with this bit indicated for clearing, any 
temporary privileges that the job has or had are permanently lost. 


JFFPP Clearable by any caller. Clearing JFFPP indicates that this job no longer 
wants the state of the hardware floating-point unit (if any) to be swapped 
along with the job’s normal context information. 


JFSPRI Clearable by any caller. Clearing JFSPRI lowers the job’s run priority by 
one-half step. That is, it clears bit 2 of the system- controlled low-order 
three bits of the run priority. See the SET JOB command RSTS/E System 
Manager’s Guide. 


JDFSTM Clearable by any caller. Deactivates the fast-map facility and restores 
normal IOT trapping. If you leave this bit set, clear all the others. 


All other bits in the XRB are masked off. 


Data Returned 
The .CLEAR directive does not return any meaningful data. 


Errors 
No errors are possible with the .CLEAR directive. 


Example 

The following code clears the JFLOCK bit: 

CALL CLRXRB ;CLEAR XRB 

MOV #JFLOCK, XRB+XRLEN ;SET JFLOCK FOR CLEAR 
. CLEAR 


See Programming Hints for information on the CLRXRB routine. 


3.9 .CMDLN—Read/Write Command Line 


Form 
.CMDLN 


Function 


The .CMDLN directive lets programs pass up to 1K words of data (2048 charac- 
ters) when chaining to another program. DCL uses this capability to pass long 
command lines to some server programs. If possible, the .CMDLN directive stores 
the data in core common. If not, it stores the data in XBUF. 


NOTE 


The read function deletes the command line after it has been read, 
therefore the command line can only be read once. 


Privileges Required 
None 


Data Passed (Write a Command Line) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


0 XRLEN 
2 XRBC 
4 XRLOC 


6 


XRB+XRLEN The length of the command line to be written, in bytes. 


XRB+XRBC The length of the command line to be written, in bytes. 

XRB+XRLOC The starting address of the command line to be written. (See the 
section "XRB (Transfer Request Block)" in Chapter 2 for more informa- 
tion.) 

Errors 

BADCNT XRB parameters were invalid, or the command line was too long. 


NOBUFS Not enough XBUF was available to store the command line. 
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Data Passed (Read a Command Line) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


oe 
niin | 


XRB+XRLEN The length of the buffer to receive the command line, in bytes. 
XRB+XRBC Zero to indicate a read operation. 


XRB+XRLOC Starting address of the area where the command line is placed. (See 
the section "XRB (Transfer Request Block)" in Chapter 2 for more 
information.) 


0 XRLEN 


4 XRLOC 
6 

10 

12 


14 


Data Returned 


XRB+XRBC The length of the command line read, in bytes. 


Errors 


NOSUCH There was no command line to be read. 
LINERR The command line was too long for the user’s buffer. 
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3.10 .CORE — Change Memory Size 


Form 
.CORE 


Function 


The .CORE directive asks the monitor to change the amount of memory currently 
allocated for the user job image (low segment) for this job. The monitor preal- 
locates space for a user job image at the time a .RUN directive is issued. The 
space is based on the size of the file Gf PF.CSZ = 1 in the P FLAG word of the 
pseudovector region) or is equal to the PMSIZ word in the pseudovector region. 


NOTE 


If the I&D Space split is enabled, .CORE alters only the size of the 
D-Space. 


You can change this initial size with the .CORE directive as many times as you 
want, as long as the requested size falls within the minimum and maximum 
memory range for the current run-time system. 


The monitor first checks the size requested against maximum and minimum 
values, using this algorithm: 


lKword < P.MSIZ < size requested < private < P.SIZE < system 
with .CORE maximum maximum 
for job 


The monitor determines the maximum allowable amount of space for a user job 
image as follows: 


e Set <max> (the maximum size that a job image can be) to the system-wide 
maximum. This maximum is set by the system manager at startup time (see 
the SWAP MAX discussion in the RSTS/E System Installation and Update 
Guide). 


e Ifthe maximum user job image size imposed by the run-time system (P.SIZE 
in the pseudovectors) is less than the current <max>, set <max> to P.SIZE. 


e If the job’s private memory maximum is less than <max> and if the caller 
does not have EXQTA privilege, then set <max> to the job’s private memory 
maximum. The system manager can set a particular job’s private memory 
maximum with the SET JOB/SIZE=n command. You can also set a private 
memory maximum with the UU.PRI subfunction of the .UUO directive (in 
this chapter). A job’s private memory maximum is initially defaulted to the 
system maximum. 


e The size of I-Space and the size of D-Space can not exceed 32K words each. 
Thus, the size requested with .CORE is checked against <max>, as determined by 
the four previous steps. The size requested with .CORE is also checked against a 


minimum (the P.MSIZ word in the pseudo vectors, which must be greater than or 
equal to 1K words). Any size between P.MSIZ and <max>, inclusive, is legal. 
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There are two special cases: 


If the size requested with .CORE is exactly equal to the run-time system’s 
minimum size (P.MSIZ), that request is considered legal even if the requested 
size is greater than the job’s private maximum. 


If the size requested with .CORE is less than the job image’s current size and 
within the allowable bounds for the run-time system, but it is still larger than 
the private maximum, that request is considered legal. This could happen 

if the caller had EXQTA privilege, allowing the current size to be greater 
than the private maximum, and then dropped EXQTA privilege. The monitor 
would still allow the size greater than the private maximum. 


If .CORE requests a decrease in job image size, no further checks are made. 

If .CORE requests an expansion and the size is legal according to the cases 
previously described, the monitor then determines if the expansion overlaps any 
windows created by CRAFQ or CRAW$. If there are no overlaps, .CORE proceeds. 
If there is an overlap, the monitor rejects the .CORE expansion under any of the 
following conditions: 


If separate I- and D-Space hardware does not exist. 
If the APR mask value in XRB+XRBC is zero. 


If the overlapped window was created in D-Space (WS.UDS bit is set). 
Mapping a dynamic region can produce this. 


If the expansion would use an APR marked for protection by the APR mask 
in XRB+XRBC. 


The APR mask tells the monitor how to handle the D-Space mapping when using 
concurrent APR windows. The possible options are: 


Mask 

Value Meaning 

0 Concurrent window usage is not allowed. The monitor rejects .CORE with 
an error if it finds any overlap with a created window. The RSTS/E RSX 
emulator handles the EXTK$ directive in the same way. This insures that 
all I-Space libraries in use also have D-Space as well. 

1 Concurrent window usage is allowed and all libraries in use are presumed 


to be I-only code and all D-Space is available for the task. The RSX-11/M- 
PLUS native operating system handles the EXTK$ directive in the same 
way. 


Mask 
Value Meaning 


1l+n The value n is the inclusive OR of values representing the D-Space APRs 
being protected. If an APR is protected, it means the D-Space for that 
APR remains mapped along with the I-Space window at the same APR. 
If the .CORE expansion also requires this APR, the request is rejected 
with an error. This is the equivalent of the EXTM$ directive under both 
RSX-11/M-PLUS and the RSTS/E RSX emulator. Bit 0 must be set. 


Value D-Space APR Protected 


1 None, all 8 APRs are available for task data 
3 APR 1 and above protected 
5 APR 2 and above protected 
11 APR 3 and above protected 
21 APR 4 and above protected 
Al APR 5 and above protected 
101 APR 6 and above protected 
201 APR 7 and above protected 


This mask should be treated as a fence; that is, the lowest bit (other than 
bit 0) determines the protection. (41 and 341 are equivalent and protect in 
APRs 5,6 and 7.) 

This mask passes the information to the monitor at execution time about the 
D-Space requirements for the libraries associated with this job, accumulated 
by the Task Builder. The Task Builder, if requested, passes this mask in 

a location called $$TSKP. See the RST'S/E Task Builder Manual for more 
details. 


If .CORE requests a legal expansion that cannot be made in place, that is, if there 
is not enough free memory available for the expansion, the job is swapped out 
and swapped back in at the larger size. (This swap occurs even when JFLOCK = 
1 in the keyword (KEY).) 


When a user job image expands, the content of the newly added memory is zeroed 
as protection against a malicious user reading memory to look for passwords. 


NOTE 


Do not use this directive from a user job image running under the RT- 
11 run-time system. Expanding memory size should be done through 
the RT-11 emulator, using the appropriate RT-11 directive. 


When the image runs under the RSX run-time system, use the EXTK$ or EXTM$ 
directive to extend the task size, so that subsequent GTSK$ directives can return 
the task size correctly. 


Privileges Required 


EXQTA to exceed private memory maximum. 
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Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
3 0 or D-APR mask | 2 XRBC 
. , 
XRB+XRLEN The desired size for the user job image, in K words. 


XRB+XRLEN+1 If this byte contains a -1, the user is requesting that the I&D 
| APRs be split to map different physical memory. XRB+XRLEN 
is the requested size of the D-Space. The I-Space size is fixed at 
the job’s current size. If this byte contains a -1 and XRB+XRLEN 
contains a zero, the I&D split is disabled. 


XRB+XRBC Either zero or the D-Space APR mask. If the value is zero, .CORE 
acts as the EXTK$ directive; otherwise, .CORE acts as the EXTM$ 
directive. See Chapter 5 for descriptions of these directives. If you 
use the D-Space APR mask, the first bit must be set. 


Data Returned 


Other than a possible error in the byte 0 of the FIRQB, the .CORE directive does 
not return any meaningful data. 


Errors 


BADFUO The program is requesting that the I&D Space be split, but it cannot be split 
or is already split. 


EDBMCE The requested user job image size is illegal. It is either too large or too 
small, or it overlaps a mapped window. 


ERRERR The program is requesting use of separate I&D Space but the hardware does 
not exist on this system. 7 


INUSE There is outstanding asynchronous I/O for this job. 


Example 


The following code requests a user job image of 24K words: 


CALL CLRXRB ;CLEAR THE XRB 
MOVB #24 .,XRB+XRLEN ;SET XRB TO INDICATE 24K WORDS 
- CORE 


See the section "Programming Hints" for information on the CLRXRB routine. 
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3.11 .DATE — Return Current Date and Time 


Form 
.DATE 


Function 


The .DATE directive returns the current date and time, the current program 
name (as installed by the NAME directive), and the current run-time system 


name in the XRB. 


Privileges Required 


None 


Data Passed 


The .DATE directive does not pass any meaningful data. 


Data Returned 


Mne-— Octal 
monic Offset 


XRB 


Octal Mne- 
Offset monic 


1 current date, in system internal format | O XRLEN 
3 CO minutes until midnight | 2 XRBC 
7 program name in RADS50 format 6 XRCl 
(2 words) 
11 (as installed with NAME) 10 
13 run—time system name in RAD50 format 112 XRTIME 
(2 words) 
15 14 
XRB+XRLEN The current date, in system internal format. The monitor calcu- 
lates the date as: 
[(year - 1970) * 1000.] + day-within-year 
where day-within-year is 1 for January 1, 2 for January 2, and so 
forth. (Every leap year, the day-within-year value for March 1 and 
following is one higher than in other years.) 
XRB+XRBC The number of minutes until midnight. A value of 1440 is mid- 
night; 720 is noon; 0 is never returned. 
XRB+XRLOC The number of seconds until the next minute. A value of 60 is 


XRB+5 


xx:xx:00; 1 is xx:xx:59; O is never returned. 


The number of ticks until the next second. A tick is either 1/60th 
or 1/50th of a second, depending on the clock in use and/or the 
line frequency. (Systems running with the KW11P clock at crystal 
speeds, rather than at line frequency, or systems running the 
11/73, 11/83, 11/84, 11/93, or 11/94 800 Hertz clock, have a tick of 
1/50th of a second. Otherwise, if the system is operating with a 60 
Hz power line, a tick is 1/60th of a second.) 
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XRB+XRCI The current program name (as set by the most recent .NAME 


directive); two words in RAD50 format. 
XRB+XRTIME 


The current run-time system name; two words in RAD50 format. 
Errors 
No errors are possible with the .DATE monitor call. 


Example 


Since no data is passed to the monitor, the call is: 
.DATE 
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3.12 .ERLOG — Log an Error from RTS 


Form 
-ERLOG 


Function 


You can issue the .ERLOG directive only from the high segment (run-time sys- 
tem). It allows the run-time system to log an error into the RSTS/E error log 
file, which can then be printed by the system manager (see the RSTS/E System 
Manager's Guide). For example, you might want to place an entry into the 
RSTS/E error logging scheme on a hardware floating-point unit exception that 
has an illegal error code because the monitor makes no such checks. 


You can issue this directive only from the job’s current run-time system (high 
segment). Since this call does not require privilege, the monitor does not let users 
fill up the system error log with unimportant errors. If .ERLOG is issued from 
the user job image (low segment), RSTS/E ignores it. 


Privileges Required 


None 


Data Passed 


The .KRLOG directive records in the system error log file the contents of the 
program counter (PC) and program status word (PS) at the time of the call, as 
well as the contents of the general registers (RO through R5). These registers will 
then be displayed at the system manager’s request. Hence, the registers should 
contain whatever information you want to record when the .ERLOG is executed. 


Data Returned 
The .ERLOG directive does not return any meaningful data. 


Errors 
No error is possible with EERLOG. 


Example 
If the general registers contain relevant information, the call is: 


-ERLOG 
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3.13 .EXIT — Exit to Default Keyboard Monitor 
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Form 
EXIT 


Function 


The .EXIT directive returns control to the system default keyboard monitor (DCL) 
at the PNEW entry point (see Chapter 2). When a program exits, it normally 
passes control to the job’s keyboard monitor with the .RTS directive. You can use 
the .EXIT call as a backup to return control to the default keyboard monitor if the 
RTS fails, or for any other reason when you want to enter the default keyboard 
monitor at the entry point specified by PNEW. The .EXIT directive needs no 
arguments and never returns in line to the caller. 


Privileges Required 


None 


Data Passed 


The .EXIT directive needs no arguments; however, the three words beginning at 
XRB+10 are passed unaltered to the default keyboard monitor. The monitor also 
passes information to the default keyboard monitor when .EXIT is executed. See 
the discussion of the P NEW entry point in Chapter 2. 

Data Returned 

The .EXIT directive does not return any meaningful data; control never returns 

in line. 

Errors 


No errors are possible with .EXIT. 


Example 


Since no data is passed or returned with .EXIT, the call is: 
EXIT 


NOTE 


Do not use this RSTS/E directive from a user job image running under 
the RT-11 run-time system. The correct way to terminate such a 
program is to exit to the RT-11 emulator, which then returns control to 
the job’s keyboard monitor. 


3.14 .FSS — Check File Specification String 


Form 
FSS 


Function 


The .FSS directive examines a string of characters presumed to be a file specifi- 
cation and, if possible, converts it to the internal RSTS/E file specification format 
(FIRQB format). The monitor returns information to the XRB describing what 
it found in the string and returns the converted file specification to the FIRQB. 
Thus, programs that manipulate files can use .FSS to translate a user-typed 
string to the FIRQB format. 


The monitor examines the string from left to right and stops without error when 
it finds: 


e The end of the string. 
e An equal sign (=), which is ASCII code 075. 
e A semicolon (;), which is ASCII code 073. 


e Aslash (/), which is ASCII code 057, that is followed by anything other than 
the following switches, which the monitor translates to the FIRQB format: 


— /CLLOUSTERSIZE):(-][#]n[.] 


where n is the cluster size used in opening files and devices. The variable 
n can specify a value ranging from -32768 through 32767. 


—- /MO[DE]:[#]n[.] 


where n is the mode used in opening files and devices. The variable n can 
specify a value between 0 and 32767. 


— /FILLESIZE):[#]n[.] or /SI[ZE):[#In[.] 


where n is the filesize used in opening files and devices. The value of 
n defines the file’s size in 512-byte blocks and can be in the range 0 to 
8,388,607 blocks. 


— /PO[SITION]:n 


where n is the position used in creating files (to position block 1 of the file 
at a device cluster). The variable n can specify a value between -2 and 
65,535. 


— /PRLOTECTION]:[#]InL.] 


where n is the protection code used in opening or creating files. The vari- 
able n can specify a value between 0 and 255. The value of n determines 
the file’s protection from users; see the RSTS/E System User’s Guide. 


The brackets ([ ]) in the previous switches enclose optional characters. Where 
more than one character is enclosed in brackets, any or all of the enclosed 
characters can be omitted. For example, MO, MOD, and MODE would all be 
accepted and the following quantity translated to the mode location in the 
FIRQB. 


The value n is assumed to be decimal, unless the optional pound sign [#] 
appears, indicating that n is octal. The optional decimal point also indicates a 
decimal value. 
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e A comma (,), which is ASCII code 054. An exception is the comma separating 
the project and programmer numbers in a PPN. 


The monitor translates the components in a file specification string as follows: 


device name A device name can be either a logical device name or a physical device 
name: 
logical A logical device name is a string of alphanumeric 


physical: 


characters or dollar sign ($) or underscore (_), termi- 
nated with a colon (:). The logical name can contain 
the $ character anywhere except as the first char- 
acter. Only the first 15 characters are examined; 
the remainder are ignored. If the logical name does 
not contain a $ character, the monitor checks the 
name against the user’s own logical device name 
assignments in the extended logical portion of the job 
header. If the monitor finds a definition, it returns 
the physical device name associated with that logical 
device name to the FIRQB. If the logical name is not 
found in the user-logical area or if the logical name 
contains a $ character, the monitor makes a search of 
systemwide logical names. If the logical is not found 
in the logical lists, the monitor searches the logical 
table given in the XRB. If the logical name is not 
found, the monitor returns the logical device name 
and sets a flag in the XRB to indicate that it could 
make no association. For a logical device name be- 
ginning with an underscore (_), the monitor does not 
attempt any translation to a physical device name. 


A physical device name consists of two alphabetic 
characters optionally followed by digits and ended 
with a colon (:). The digits are translated as decimal 
and must have a value between 0 and 127 (decimal). 
Leading zeros are allowed. 


For some devices (for example, terminals) a physical 
name can also be specified as a two-letter device 
name, a one-letter controller identifier, and a number 
specifying the unit on that controller. For example, 
TTG2: is the third terminal on a DZ11 controller. 


account or PPN 


A PPN can be expressed either as a single special character or as two 
separate numbers enclosed in square brackets [] or parentheses ( ) 
and separated by a comma. 


The following special characters are translated as: 


$ 


! 


%o 


[n,m] 


(n,m) 


The dollar sign ($) is equivalent to [1,2]. 

The exclamation point (!) is equivalent to [1,3]. 

The percent sign (%) is equivalent to [1,4]. 

The ampersand (&) is equivalent to [1,5]. 

The number sign (#) is translated to the caller’s group library. 
It is always equivalent to [proj,0] where proj is the project 
number of the user issuing the .FSS directive. 

The at sign (@) is translated to the caller’s assignable PPN, 
the USRPPN value (see Chapter 2). If USRPPN is set, its 
value is placed in the FIRQB at offset FQPPN. If USRPPN is 


zero, a string with an @ causes an error. 


NOTE 


Digital does not recommend 
the use of the special charac- 
ters !, %, &, #, or @. They are 
provided only for compatibil- 
ity with pre-V9.0 releases of 
RSTS/E. 


This is the explicit construct for a PPN. The value n specifies 
the project number, and m specifies the programmer number. 
The variables n and m can specify any value from 0 through 
254, except for [0,0]. If a number sign (#) precedes either n or 
m, the string is assumed to specify an octal value. Hither n 
or m, or both, can also be the asterisk (*). The * is converted 
to 255 and placed in its corresponding FIRQB location. The 
asterisk character indicates a wildcard specification. 

Hither n or m, or both, can be omitted; in that case, the 
monitor uses the corresponding part of the user’s PPN. For 


example, [,] or [] specifies the user’s PPN; [,0] is equivalent to 
#. 


This is an alternate way to specify an explicit PPN. The 
same rules for n and m apply as when they are enclosed by 
brackets. 


NOTE 


Digital does not recommend 
the use of parentheses in 
the PPN specification. This 
format is provided only for 
compatibility with pre-V9.0 
releases of RSTS/E. 
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file name 


type 


protection code 


A file name can consist of alphanumeric characters and the question 
mark (?). It is the only field in the file specification with no explicit 
delimiter. Only the first six characters are examined; the rest are 
ignored. The asterisk character (*) is also an acceptable file name. It 
is translated to two words of RAD50, where each RAD50 character 
is the unused code (29). Each ? character is also converted to this 
unused code. This indicates that the file name field is a wildcard. 
(The LOKFQ subfunction of CALFIP and UU.LOK subfunction of 
-OUO can be used to look up wildcard files.) The asterisk can also 
represent trailing question marks. *.FIL and A*.FIL are legal file 
names; A*Z.FIL is illegal. 


A file type can consist of alphanumeric characters and the ? charac- 
ter, preceded by a. character. The * character is also an acceptable 
file type. It is translated to one word of RAD50, where each RAD50 
code is the unused code (29). Each ? character in the file type is also 
converted to this unused code. This indicates that the file type field, 
or character in the file type field, is a wildcard. The asterisk can also 
represent trailing question marks. FILE.* and FILE.A?® are legal file 
names; FILE.*Z is illegal. 


If given, the file type must always follow the file name. 


A file protection code can consist of numeric digits enclosed by angle 
brackets <>. The general form of a protection code is <nnn>, where 
n may be numeric characters indicating a value from 0 through 255. 
If the numeric characters are preceded by a # character, they are 
converted as specifying an octal value. Alternatively, the protection 
code can be specified using the /PROTECTION switch. If no file 
protection code is specified in the string and a default value has been 
assigned in USRPRT (see Chapter 2), the default value is placed in 
the FIRQB. 


These special characters can appear in the string in any order, with the exception 
of the file type and PPN. The file type must follow the file name, if specified. 


In addition, if the device name is a system or user logical device name that has 
an account (PPN) associated with it, the position of an explicit PPN in the file 

specification string is significant. If the order is device:[PPN], then the explicit 
PPN overrides the PPN associated with the logical device name. If the order is 
[PPN/device:, RSTS/E displays the error message ?Iillegal device name. 


NOTE 


Do not use this directive from a user job image running under the RT- 
11 run-time system, since the user logical area is not in the standard 


location. 


Privileges Required 


None 


Data Passed 


Mne— Octal 
monic Offset 


XRB 
Octal Mne— 
Offset monic 


1 length of the string, bytes 0 XRLEN 
3 length of the string, bytes 2 XRBC 

5 starting address of the string 4 XRLOC 
7 FETT ATT TT AAT IAG AIA Ta 6 
11 length of nonstandard user defaults 10 XRBLK 
13 starting address of nonstandard users | 12 XRTIME 
15 PL PLETAAL LEAL ELT ELS 14 

XRB+XRLEN The length of the character string to be translated, in bytes. 

XRB+XRBC The length of the character string to be translated, in bytes. 

XRB+XRLOC The starting address of the string to be translated. (See the 
section "XRB (Transfer Request Block)" in Chapter 2 for more 
information.) 

XRB+XRBLK If the user logical information (USRPPN, USRPRT, and the 
extended logical area of the job header ) is in its standard location, 
this word is passed as zero. If the user logical information is 
in some nonstandard location, the beginning address goes here. 
Digital does not support the nonstandard location and strongly 
recommends you use only standard locations. 

XRB+XRTIME If the word at XRB+XRBLK is nonzero, then this word defines 


Data Returned 


Mne- Octal 
monic Offset 


the starting location for the user logical information. (The order 
of the information is assumed to be the same as in its standard 
location; that is, the user logical PPN, user logical protection code, 
user logical device name table. The format is also expected to 

be the same (see the descriptions of USRPPN, USRPRT, and the 
USRLOG area in Chapter 2 for details). 


XRB 
Octal Mne- 
Offset monic 


| ) 
; ) 
15] deviceaeccriplsn 14. XRMOD 


FSS 3-85 


3-86 .FSS 


XRB+XRBC 


XRB+XRLOC 


XRB+XRBLK 


A count of the untranslated characters in the string. If all characters 
were translated, the value of this word is zero. 


The address of the first untranslated byte of the string. If 
XRB+XRBC is zero, this word identifies the end of the string. (See 
the section "XRB (Transfer Request Block)" in Chapter 2 for more 


information. ) 


Bit flags describing the translated string. Note that this word is the 
same as "flag word 2" for the BASIC-PLUS file name string scan SYS 
call (see the RSTS/E Programming Manual). 


Bit Setting 


0 Set 
Clear 
1 Set 
Clear 
2 Set 
Clear 
3 Set 
Clear 
4 Set 
Clear 
5 Set 
Clear 
6 Set 
Clear 
7 Set 
Clear 


Meaning 
A file name was found in the source string; two 


words in RAD50 format at FIRQB+FQNAM1. 


No file name was found (and bits 1 and 2 of 
this word are also 0). 


The translated file name consisted of a single * 
character and has been translated to two words 
at FIRQB+FQNAM1 consisting of the RAD50 
representation of the string "?7?777?". 


The translated file name was not an * charac- 
ter. | 


The file name contained at least one ? charac- 
ter. 


The file name did not contain any ? characters. 
A period (.) was found in the source string. 


No period was found, implying that no file type 
was specified (and bits 4, 5, and 6 of this word 
are also 0). 


A file type was found; that is, the field after the 
period was not null. 


No file type was found (the field after the 
period was null), and bits 5 and 6 of this word 
are also 0. 


The file type was an * character and is re- 
turned in the word at FIRQB+FQEXT as the 
RAD50 representation of the string "???". 


The file type was not an * character. 

The file type contained at least one ? character. 
The file type did not contain any ? characters. 
A PPN was found in the source string. 


No PPN was found (and bits 8 and 9 of this 
word are also 0). 


10 


11 


12 


13 


14 


15 


Set 


Clear 


Set 


Clear 


Set 
Clear 
Set 


Clear 


Set 


Clear 


Set 
Clear 


Set 


Clear 


Set 


Clear 


The project number was an * character. That 
is, the PPN was of the form [*,n].) RSTS/E 
returns a value of 377 at FIRQB+FQPPN+1. 


The project number was not. an * character. 


The programmer number was an * character. 
That is, the PPN was of the form [n,*]. RSTS/E 
returns a value of 377 at FIRQB+FQPPN. 


The programmer number was not an * charac- 
ter. 


A valid protection code was found. 
No protection code was found. 


No file protection code was found in the string, 
but there was a default output file protection 
code in location USRPRT. The default has been 
returned in the FIRQB. 


The user-assignable default protection code (at 
location USRPRT) was not used. Hither zero 
or the protection code given in the string is 
returned to the FIRQB. 


A colon (:), but not necessarily a device name, 
was found in the source string. 


No colon was found (no device was specified); 
bits 13, 14, and 15 of this word are also 0. 


A device name was found in the source string. 


No device name was found; bits 14 and 15 of 
this word are also 0. 


The device name in the string was a logical 
device name. 


The device name in the string was an actual 
device name; bit 15 of this word is also 0. 


This bit set indicates an invalid device name. 
(The characters that were specified are simply 
returned at FIRQB+FQDEV, FIRQB+FQDEVN, 
and FIRQB+FQFLAG as three words in RAD50 
format.) This bit can be set in one of two ways: 


e Ifthe device name contained an underscore 
but was not a recognizable device name for 
any device on the system, this bit is set. 


e If the device name did not contain an 
underscore but the name could not be 
translated to a physical device name, this 
bit is set. 


The device name specified, if any, was either 
an actual device name or a logical device name 
to which a physical device has been assigned. 
The physical device name has been returned 
to the word at FIRQB+FQDEV as two ASCII 
characters, and the unit information has been 
returned appropriately at FIRQB+FQDEVN. 
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XRB+XRTIME Remaining bit flags describing what was translated. Some of these 
bits duplicate information returned at XRB+XRBLK. Digital recom- 
mends that you use the bits at XRB+XRBLK to allow for enhance- 
ments in future releases. Note that this word is the same as "flag 
word 1" for the BASIC-PLUS file name string scan SYS call, see the 
RSTS/E Programming Manual. 


Bit 
0 


10 


11 


12 
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Setting 
Set 
Clear 
Set 


Clear 
Set 
Clear 


Set 
Clear 


Set 


Clear 
Set 


Clear 


Set 


Clear 
Set 


Clear 
Set 


Clear 


Meaning 

The /CLUSTERSIZE:n switch was specified. 
The /CLUSTERSIZE:n switch was not specified. 
Hither the /MODE:n or /RONLY switch was 
specified. 

Neither the /MODE:n nor the /RONLY switch 
was specified. 

The /FILESIZE:n or /SIZE:n switch was speci- 
fied. 

Neither the /FILESIZE:n nor the /SIZE:n 
switch was specified. 

The /POSITION:n switch was specified. — 

No /POSITION:n switch was specified. 

(Not currently used.) 

A file name was found in the source string; two 
words in RAD50 format at FIRQB+FQNAM1. 
Note that this is the same meaning as for bit 0 
at XRB+XRBLK. 


No file name was found in the source string. 


A period (.) was found in the source string. 
Note that this is the same meaning as for bit 3 
at XRB+XRBLK. 


No period was found in the source string, 


implying that no file type was specified either. 


A PPN was found in the source string. Note 
that this is the same meaning as for bit 7 at 
XRB+XRBLK. 


No PPN was found. 


A valid protection code was found. Note that 
this is the same meaning as for bit 10 at 
XRB+XRBLK. 


No protection code was found. 


A colon (but not necessarily a device name) was 
found in the source string. Note that this is the 
same meaning as for bit 12 at XRB+XRBLK. 


No colon was found, implying that no device 
could have been specified. 


13 Set Device name was specified and was a logi- 
cal device name. Note that this is the same 
meaning as for bit 14 at XRB+XRBLK. 


Clear Device name (if specified) was an actual device 
name. (If device name was not specified, this 
bit is also Q.) 


14 (Not currently used.) 


15 Set Source string contained wildcard characters 
(either ?, *, or both) in file name, type, or PPN 
fields. In addition, the device name specified, 
although a valid logical device name, does 
not correspond to any of the logical device 
assignments currently in effect or contains an 
underscore as the first character. Flag word 2 
contains more specific information. 


XRB+XRMOD The device description (the same information returned by the BASIC- 
PLUS STATUS variable and returned at FIRQB+FQFLAG when a 
file or device is opened with the OPNF'Q or CREFQ subfunctions of 
CALFIP). The device handler index is in the low byte and descriptive 
flags are in the high byte. 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 | Te 


FQSIZM 5 “MSB of f file size os GULL 


11 | file name in RAD50 format | FQNAM1 
13 | _ (tirst 2 wore) 


15 | file pe in RADSO format (1 word) | FQEXT 


17 LSB of file size FQSIZ 
21 TTA TTT 


23 | mode parametcl FQMODE 


25 | ard | word o} eg )cal name pe translated) FQFLAG 


37 posits sarawelst (DCN for first pisck) | FQNENT 


NOTE 


For each of the following field definitions that begin with the word "If," 
a corresponding statement applies: "If not, the field is left alone." That 
is, you can insert values in the FIRQB before executing the .FSS to 
serve as default values for fields when the .FSS returns no result. 
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FIRQB+FQJOB 
FIRQB+FQSIZM 


FIRQB+FQPPN 


FIRQB+FQNAM1 


FIRQB+FQEXT 


FIRQB+FQSIZ 


FIRQB+FQMODE 


FIRQB+FQPFLG 


FIRQB+FQDEV 


FIRQB+FQDEVN 


The current job number times two. 


If a /FILESIZE:n or /SIZE:n switch was specified, the most signifi- 
cant bits of the file size are contained in this byte. 


If a PPN was part of the translated string or if a logical name 
was found to be the same as a system or user logical name with 
an associated PPN, this word contains the binary value of that 
PPN. The project number is in the high byte; the programmer 
number in the low byte. Any value returned here by .FSS has 
been verified by the monitor as being within the range for PPNs 
on a RSTS/E system. 


If a file name was encountered, it is translated to two words 
of RAD50, beginning at this location. If less than 6 characters, 
the file name is left-justified and padded with blanks (0 RAD50 
characters). 


If a file type was encountered, it is translated to one word of 
RAD50, beginning at this location. If less than 3 characters, 
the file type is left-justified and padded with blanks (0 RAD50 
characters). 


If a /FILESIZE:n or /SIZE:n switch was encountered, the value of 
n is translated to binary and the LSB of the value are placed in 


this word. The MSB are placed in the byte at FIRQB+FQSIZM. 


If a /MODE:n switch was encountered, the value specified is 
translated to binary and returned in this word. Bit 15 is set to 
indicate that a mode switch was translated and to differentiate 
between a mode of 0 and no mode at all. (Note that bit 15 must 
be set for a mode value to work on opens.) 


If a file protection code was encountered, a word is returned 
here. The high byte (FIRQB+FQPROT) is the binary value of 

the protection code, and the low byte (FIRQB+FQPFLG) is 255. 
Setting the low byte indicates that a protection code was specified 
and differentiates a protection code of zero from no protection code 
at all. 


If a device name was specified, it is returned here as two ASCII 
characters. If less than two characters were specified, the device 
name is left-justified and padded with spaces (ASCII 32.). 


If a device name but no explicit unit number was specified, this 
word is zero. If an explicit unit number was specified, then 
that unit number is in the low byte and 255 is in the high byte. 
Setting the high byte indicates an explicit device number and 
differentiates a device number of zero from no device number at 


all. 


NOTE 


If a syntactically correct logical device name was encountered that 
could not be translated to a physical device name, then the first six 
characters of the logical device name are returned as two words of 
RAD50 starting at offset FQDEV and the next three characters are 
returned as one word of RADS50 at offset FQFLAG. Characters beyond 
the first nine are not returned. 


FIRQB+FQCLUS If a /CLUSTERSIZE:n switch was encountered, the value of n is 


returned here, in binary. 


FIRQB+FQNENT If a /POSITION:n switch was encountered, the value of n is re- 


Errors 
BADCNT 
BADNAM 


BADSWT 
BDNERR 


Example 


turned here, in binary. (The value n is the device cluster number 


for the first block of the file.) 


The first three words of the XRB are illegal, or an odd or illegal address for 
nonstandard user logical table. 


Some illegal specification occurred in the string. .FSS found a sign bit set 
on at least one character. 


Some .FSS switch was encountered, but it was in an illegal format. 


The numeric argument to one of the .FSS switches was illegal. 


The following code causes the monitor to scan a string beginning at location 
BUFFER as a possible file name. BUFFER is defined as an 80-byte area and is 
filled with zeros to terminate the string scan if what the user typed did not fill 
the buffer. For example: 


BUFFER: 


- BLKWO 40. 


(read string into BUFFER from terminal) 


CALL CLRXRB 


MOV #80.,XRB+XRLEN ;DEFINE LENGTH 

MOV #80.,XRB+XRBC ;DEFINE LENGTH AGAIN 
MOV #BUFFER, XRB+XRLOC ; START OF BUFFER 
-FSS 


(test for error; if none, try open) 
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Form 
.LOGS 


Function 

The .LOGS directive: 

e Translates a system logical device name to a physical device name 
e Translates a user logical device name to a physical device name 

e Translates RAD50 format to ASCII 

e Verifies that a physical device name is valid 


e Obtains generic information about a particular device 


You specify either a logical device name, a physical device designation (name 
and, if relevant, unit number), or both, in the XRB and the FIRQB. The monitor 
compares the logical device name specified, if any, against the selected logical list 
(system or user). If it finds a match, the monitor returns the device designation 
associated with the logical device name to the FIRQB. This physical device 
designation consists of a name, unit number, and in some cases, a PPN. 


You can use the .LOGS directive simply to translate the RAD50 text stored in 
the XRB into ASCII text using the same rules of translation that .FSS uses. The 
number of words that are illegal in RAD50 and the number of translation rule 
violations are returned to the caller. 


The underline character (_) is illegal in RAD50 but legal in logical names. To 
resolve this, RSTS/E stores underline characters as periods (.) internally. When 
a logical name that includes an underline is translated to RAD50, you must 
substitute the period character. (If you use .FSS to generate the ae text, this 
substituion happens automatically.) 


RSTS/E provides two translation functions: one returns a period when it finds 
a period, and the other returns an underline when it finds a period. In each 
case, the input data is in the XRB in RAD50 format. XRB+0 must be nonzero; 
otherwise .LOGS just returns the device status of the device in FQDEV. 


.LOGS Subfunctions: There are six subfunctions of the .LOGS directive. 


FQDEV Value Meaning 

-2 Translate the logical in the XRB, using the user logical list instead 
of the system logical list. 

-3 Translate the RAD50 data in the XRB into an ASCII string, using 
the rules for logicals ("." maps to "_"). 

-4 Translate the RAD50 data in the XRB into an ASCII string without 
mapping ("." is returned as "."). 

-1 Translate the logical in the XRB using the system logical list. 

0 Use SY: as the physical device name. 

Physical device As two ASCII characters, overriden if the logical contains a device 

name also. 


Next, the monitor checks the physical device designation (either the one passed 
or the one returned by the monitor in the logical-name translation) to be sure it 
is valid. If so, information describing the device is returned in the FIRQB. 


Privileges Required 


None 
Data Passed 
XRB 


Mne- Octal Octal Mne- 
monic Offset | Offset monic 


1 | 0 XRLEN 
3 | logical device name in RADS50 format 2 
5 | (5 words) 4 
7 6 
11 10 
13 PELEEPET LIAL EIATT IT Td 12 
VEEPLELT CL EL EL ALE ELLE 
15 | 14 


EP ELAA TATT ICT ALLL A EI 


XRB+XRLEN The logical device name to be checked is passed as five words in RAD50 
format beginning at this location. If only a physical device name check 
or description is needed, then the first word of the XRB should be 
passed as zero. The physical device name is passed in the FIRQB. 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
: 
: : 
; 
: 
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FIRQB+FQDEV The physical device name, as two ASCII characters, or one of the 


following codes: 


0 For the public disk structure (SY:). (You must also 
have 0 at offset FIRQB+FQDEVN). 
-1 For a translation from a logical device name to a 


physical device name. (A -1 is guaranteed not to be a 
valid physical device name.) 


-2 For a translation of the logical name passed in the 
XRB using the user logical table rather than the 
system logical table, which is the default. 


-3 For a translation of the RAD50 data passed in the XRB 
to ASCII data using special conversion rules. RAD50 
dot (.) characters are translated as underscores (_). 


-4 For a translation of the RAD50 data passed in the XRB 
to ASCIT data without using conversion rules. 


Other For a translation of the logical name passed in the 
XRB using the system logical tables only. 
If the first word of the XRB is zero, the .LOGS directive makes 


no translations and returns generic information about the device 


specified in FQDEV and FQDEVN. 


FIRQB+FQDEVN The unit number of the physical device name is passed in this 


byte, in binary. To indicate an explicit device number, set the 
high byte (at FIRQB+FQDEVN+1) to some nonzero value. If the 
physical device name is of the form "XY:" (that is, no unit number 
is specified), then set the entire word at this offset to zero to 
indicate no explicit unit number. 


Data Returned 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, 
5 | logical device flag: -1=N, -2=Y, O=N.A. | 4 XRLOC 
XRB+XRLOC If there was no logical device name specified or if the logical device 


name cannot be translated to a physical device name, this word is 
returned as zero. 


If the passed logical device name has a PPN associated with it, 
this word is returned as -2. If not, -1 is returned. 


XRB+XRCI Description of the device. The low byte contains the device’s 


handler index. The high byte contains a set of status flags. 


DDNFS 
DDRLO 
DDWLO 
FLGPOS 
FLGMOD 
FLGFRC 
FLGKB 
“|| 


15 14 13 12 1110 9 8, 7 0 
- device-type flags device handler index 


High Byte — Device-Type Flags 
The bits in the high byte of the flag word are set to indicate the type of device specified: 


FLGRND =1 The device is random-access. 
= 0 The device is sequential. 
FLGKB =) The device is a terminal-type device. 
= 0 The device is not a terminal-type device. 


FLGFRC =1 The device is byte-oriented. That is, the 
-READ and .WRITE directives handle data in 
byte units. 


= 0 The device is block-oriented. The .READ and 
WRITE directives handle data in block units. 


FLGMOD =1 The device accepts modifiers in .READ and 
WRITE directives. 


= 0 The device does not accept modifiers in 
-READ and .WRITE directives. 


FLGPOS =1 The device keeps track of its horizontal 
position and expands characters such as TAB 
to whatever is appropriate for the device. You 


can determine the current horizontal position 
with the .POSTN directive. 


= 0 The device does not keep track of its horizon- 
tal position. 
DDWLO =) The device is a read-only device. 
= 0 The device is not write-locked. 
DDRLO a The device is a write-only device. 
= 0 The device is not read-locked. 
DDNFS aE The device is non-file-structured. 
= Q The device is file-structured. 
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Low Byte — Device Handler Index 


Bits 0-7 of the flags word contain a handler index that indicates the generic kind of device. 


The currently defined values follow. 


Octal 

Value Symbol Meaning 

0 DSKHND All disks 

2 TTYHND All terminals 

4 Reserved 

6 LPTHND All line printers 
10 Reserved 

12 Reserved 

14 CDRHND Card reader 

16 MTAHND Magnetic tape 

20 PKBHND Pseudo keyboards 
22 RXDHND Flexible diskettes 
24 Reserved 

26 NULHND The null device 
30 DMCHND The DMC11/DMR11 DDCMP interface 
32-36 Reserved 

40 KMCHND KMC11 

A2 IBMHND IBM interconnect 
44 Reserved 

46 DMPHND DMP11/DMV11 device 
50 ETHHND Ethernet device 


XRB+XRBLK If the physical device name is valid (either the one returned by 
the monitor’s translation of logical device name or the one passed), 
this word contains the monitor’s "best guess" as a reasonable 
buffer size for this device. See the .READ and .WRITE directives 


in this chapter. 
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Mne- Octal 
monic Offset 


FIRQB+FQPPN 


FIRQB+FQDEV 


FIRQB+FQDEVN 


FIRQB 
Octal Mne- 
Offset monic 


ATTA PTAA T IDE: 0 

“ELLIE BE | 2 

PLP EVTIA TAL ITTELE | 4 

| PILLLATTLALAL LALLA ALA a 10 

PETTTALLLLLLTALLLL LLL | 12 

ELILEEIIOLE:. 14 

Nt eee 16 

TITLLTALIAL LLL LLLALLA | 20 

: 
device aaine (2 ASCII charactors): | | 30 FQDEV 

| PALI! | 34 

: 


If a logical device name was passed and it was translated to a 
device designation with an associated PPN, the PPN is returned 
in this word. Otherwise, this word is the same as before the 
.LOGS call was executed. 


The physical device name, either the one returned when a success- 
ful translation of logical device name is made or the one passed, 
if no logical device name was passed. The physical device name is 
returned as two ASCII characters. 


The physical device unit number, either the one returned when 
a successful translation of logical device name is made or the 
one passed, if no logical device name was passed. The low 

byte contains the unit number, in binary. The high byte (at 
FIRQB+FQDEVN+1) is either zero, to indicate no explicit device 
number, or nonzero, to indicate an explicit device number. 
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Data Returned—RAD50 Translation Subfunctions 


If -3 or -4 is passed at FIRQB+FQDEV, the return FIRQB contains the ASCII 
translation of the RAD50 logical names. 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 PIITIIIIIT TITAS T TI 0 
3 LIIITTII IIIT IIT TT | 2 


5 | 4 FQFIL 
7 : ASCII data 6 
11 translated 10 
13 from RAD50 12 
15 | | 14 
17 | | 16 
21 | 20 
23 22 
25 24 
27 26 


7 30 FODEV 


FIRQB+FQFIL The ASCII translation of the RAD50 data passed in the XRB. Any 
unused bytes translate as zeroes. Each RAD50 word translates 
as three ASCII characters. Translation ends at the first zero 
encountered in the XRB. Illegal RAD50 word values translate as 
three question marks (???). 


FIRQB+FQDEVN The number of illegal characters encountered. The subfunctions 
search for the following errors: 
e Leading spaces. (Trailing spaces are legal.) 


e Dollar sign ($) characters. (Only system logicals may have $ 
characters. ) 


¢ Question mark (?) characters. 
¢ Dot (.) characters (subfunction -4 only). 


FIRQB+FQDEVN+1 The number of illegal RAD50 word values detected. 


Errors 


NODEVC The physical device name (either the one passed or the one corresponding to 
the logical device name) is invalid. 
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Example 


The following code asks the monitor to check the name SYSDEV to see if it is a 
defined system logical device name and, if so, to return the physical device name 
and characteristics to the XRB and FIRQB: 


CALL CLRXRB 

MOV #*RSYS, XRB+XRLEN ;SET XRB TO TRANSLATE LOGICAL 
MOV #*RDEV, XRB+XRBC ;DEVICE NAME "SYSDEV" 

- LOGS 
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3.16 .MESAG — Message Send/Receive 


Form 


(Load FIRQB and/or XRB for appropriate subfunction) 


» MESAG 


Function 


The .MESAG directive provides access from a MACRO program to the RSTS/E 
local message send/receive services and, if your system is a DECnet/E system, to 
DECnet/E network message send/receive services. 


This section contains FIRQB and XRB formats and error descriptions for local 
message send/receive. (Unless data passed and returned show specific values for 

the XRB, it should be all zeros.) When using SEND/RECEIVE calls, you must 
clear both FIRQB and XRB, even if XRB is not used. 


For detailed information about each call, see the RSTS/E Programming Manual. 
For information about network message send/receive, see RSTS/E DECnet/E 
Network Programming in MACRO-11. 


3.16.1 Declare Receiver Subfunction 


Privileges Required 


SYSIO to declare a receiver with an unrestricted name, network server, or local 
object. EXQTA to suppress RIB or message quota checks. 
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Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 PPTEFALA TTL TAI TD 0 
3 LATTE TALE. 2 
5 ee | ITTITLALA 7 | function code =1 | “funelioneede2a | 4 FQFIL 
7 | | —_ Oo | 6 FQPPN 
| receiver name in ASCIl 
11 10 
{space fill to six bytes) 
13 12 
31 | | TT | 30 


FIRQB+FQPPN If the caller does not have SYSIO privilege, the fifth and sixth 
characters of the receiver name must be the caller’s job number as 
two ASCII digits. 


FIRQB+FQMODE Specifies the maximum number of packets that can be queued at 
any one time. See the RST'S/E Programming Manual for more 
information. Used only in an EMT logging program. 


FIRQB+FQFLAG+1 Specifies the number of packets that make up a complete message. 
See the RSTS/E Programming Manual for more information. 
Used only in an EMT logging program. 


Data Returned 


Except for a possible error code in byte 0 of the FIRQB, the declare receiver 
subfunction of .MESAG does not return any meaningful data. 


Errors 


BADCNT The specified packet maximum is out of range. 


BADFUO The receiver name, object type, and access parameters passed are inconsis- 
tent. 
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BADNAM This error can occur for one of the following reasons: 


e The receiver name passed contains nonprintable characters or leading 
or embedded spaces 


e A job without SYSIO privilege passed a nonblank receiver name whose 
fifth and sixth characters are not its job number 


e The specified local object type is invalid 


ERRERR The call you attempted requires an optional feature (such as EMT logging 
or DECnet) that is not available on your system. 


FIEXST The receiver name passed is being used by another receiver, or the local 
object type you specified is single instance and is already in use. 


INUSE The calling job already exists in the system’s list of declared receivers. This 
error may indicate a logic error in the program or that a previous program 
running under the same job number failed to remove itself from the receiver 
list before terminating. In the last case, issue a remove receiver call, and 
then reissue the declare receiver. (It is common practice to code a remove 
receiver immediately before the declare receiver call.) 


NOBUFS There were no small buffers available to hold the arguments passed in the 
declaration. Since the system’s use of small buffers is dynamic, a retry may 
succeed. 


PRVIOL This can occur for one of the following reasons: 


e The specified RIB number is out of range 
e The caller does not have the privilege required for a particular option 


QUOTA You have exceeded the RIB or message quotas. 
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3.16.2 Remove Receiver Subfunction 
Privileges Required 
JOBCTL to remove the RIB of another job. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. 
sm | 
min | 
21 LIL T ITT RD Ede 20 
23 | TIT ITL EA EEL 22 
31 | ALPE - 30 
33 RIB number | 32 FQDEVN 


FIRQB+FQSIZM The value is two times the job number of the receiver (s) you want to 
remove or zero if the receiver (s) belong to your own job. To specify 
a conditional remove, set the sign bit. For example, to conditionally 
remove receivers for your own job, set this byte equal to 200. 


When the sign bit is set, the remove operation is rejected if there are 
any messages pending for the receiver. 


Data Returned 


Except for a possible error code in byte 0 of the FIRQB, the remove receiver 
subfunction of MESAG does not return any meaningful data. 


Errors 


BADFUO The argument at FIRQB+FQSIZM was odd. It must be zero to remove the 


calling program or job number times two to remove another job. 
INUSE Occurs on a conditional remove if there are messages pending for the receiver. 


PRVIOL The caller does not have JOBCTL privilege and has attempted to remove the 
receiver ID block (RIB) of another job (that is, FIRQB+FQSIZM is nonzero). 
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3.16.3 Send Local Data Message Subfunction 


Privileges Required 


SEND to send to a restricted receiver. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


: . 
: 
6 


FQPPN 


receiver name in ASCII 


11 | 10 
(space fill to six bytes) 
13 12 
15 14. FQEXT 
17 optional user parameter string 16 
up to 20 bytes of additional 
21 user data can be specified here 20 
23 (zero fill to 20 bytes) 22 
25 24 
27 26 
31 30 
33 32 
35 34 
37 36 
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FIRQB+FQSIZM You can specify the destination in one of three ways: 


@ 


A zero value indicates that the destination is the receiver 
name that starts at FIRQB+FQPPN. 

A value equal to the job number times two indicates that 

the destination is this job number. If you do not specify a 
name (FIRQB+FQPPN = 0), the system locates the receiver 
by job number; this works only when the the receiving job 

is receiving messages on RIB 0. If you specify a name, the 
system sends to the specified receiver name. However, the 
system also checks that the receiver’s job number matches the 
value in FIRQB+FQSIZM. 

A value equal to the local object type (LOT) plus 200 indicates 
that the destination is the receiver for the specified local 
object type number. Only single-instance object types are 
valid (see the RST'S/E Programming Manual). Legal values 
are: 


LOT Receiver 

Error logger 

EMT logger 
PBS—command interpreter 
PBS—server interpreter 
PBS—user request packet 
OPSER 

13 OMS 


nD oF fF WH DD 


FIRQB+FQPPN Specifies the receiver name. If FIRQB+FQSIZM is zero, this field 


must be nonzero. 


Mne- Octal 
monic Offset 


XRB 
Octal Mne- 
Offset monic 


5 | starting address of Buller | 4 XRLOC 
: . 
XRB+XRLEN Length of the output buffer, in bytes. This value can range from 
zero through 512. 
XRB+XRBC The number of bytes to be sent. This value can range from zero 
through the size of the buffer, as specified at XRB+XRLEN. 
XRB+XRLOC Starting address of the output buffer. (See the section "XRB 


(Transfer Request Block)" in Chapter 2 for more information.) 
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Data Returned 


Mne- 


FIRQB 


Octal Octal Mine- 
monic Offset Offset monic 


1 


FQSIZM5 


Errors 


BADCNT 
BADFUO 


NOBUEFS 


NOROOM 


NOSUCH 


PRVIOL 


7 


11 


13 | 


15 


17 


21 


23 | 
25 | 


27 | 


3 1 


33 


35 


37 


3 | 


BECregeweeeene se so se) 


FEAT AAALAC TEAT ATELY 


See 7777777 
Pannen 
- TTLTALTTALTLTALIAATTA | 
77777000 
[mii 


| ieee verona rece eae | 


VAEAAA TATA ATA PATE E ST 


PLEETATTLAATT TALE T A 


LTTE ECE TE AALAT SIAL LIT 
ELEAAAT TAL LATT AL ALL HT 
LER TAEALTATLALEFATLL 


| EATEPL TELIA LV AAIIS PAA 
| EAP AVAAA TAT AIST IAG IA 


The XRB+XRLEN value is illegal. It can range from 0 through 512. 


The value at FIRQB+FQSIZM is odd. It must be zero or the receiver’s job 
number times two. 


System buffers are currently not available to store this message for the 
intended local receiver. A later retry may proceed without error. 


The number of pending messages for the intended local receiver is at its 
declared maximum, or the receiving program is hibernating. This program 
should try again later. If this error occurs repeatedly, the receiver is not 
processing messages often enough. 


The intended local receiver could not be located in the system’s list of 
declared receivers. The receiver must be declared (with a declare receiver) 
before any data can be transmitted to it. 


Some access violation has occurred. Either the receiver does not allow any 
local senders, or the sender does not have SEND privilege and the receiver 
allows only restricted senders. 


3-106 .MESAG—Send Local Data 


3.16.4 Receive Subfunction 


Privileges Required 


None 


Data Passed 


Mne- Octal 
monic Offset 


, 
3 
FQSIZM5 
7 

11 

13 

15 


17 


Mne- Octal 
monic Offset 


13 


15 


FIRQB 


[inn 
renin 
[esa meatier | tinton cons 

aiialiftar Gaaee = 0) | senderselect | 
[tin 


PL AELTAL PEAT LATE LAL FA 


M11TTTI / 
/ / | 


Pini 


XRB 


[iiniisn 
[iin 


Octal Mne- 
Offset monic 


0 
2 
4 FQFIL 
6 FQPPN 
10 


12 


22 FQMODE 


32 FQDEVN 


Octal Mne- 
Offset monic 


0 XRLEN 
2 XRBC 
4 XRLOC 
6 
10 
12 


14 
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XRB+XRLEN The size of the receive buffer, in bytes. This word can be zero 
if no user data is desired on the receive. The amount of data 
transferred from a pending message will never be greater than the 
buffer size. 


XRB+XRBC This word must be passed as zero. The monitor returns the actual 
number of bytes of user data transferred in this word location, as 
shown in the Data Returned sections. 


XRB+XRLOC The starting address of the receive buffer. (See the section "XRB 
(Transfer Request Block)" in Chapter 2 for more information.) 


Data Returned 


The Receive call returns data to the FIRQB and XRB, identifying the type of 
message received and user data, if any, to the buffer defined in the data passed. 


The FIRQB and XRB formats for the local data message follow. 


Data Returned (Local Data Message) 


FIRQB | 
Mne- Octal . Octal Mne- 
monic Offset Offset monic 
: : 
3 | IT TLLLLALLLALLALLAAA | 2 
7 J project number 6 FQPPN 
15 | 14 FQEXT 
17 | Data passed as parameters by the 16 
sender of this message. | 
21 20 
23 | 22 
25 | 24 
27 26 
31 | 30 
33 32 
35 | 34 
37 ! | 36 
FIRQB+FQNAM1 A value of 377 means the sender is detached. 
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3.16.4 Receive Subfunction 
Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LTIIIAITT IIIT AI TTT 
FALIAETA IAAL SALES EAL? 
[esse nator | traion cose =? 


| 10 


1 0 


3 2 
FQSIZM5 4 FQFIL 
7 6 FQPPN 
11 


13 12 


Zacageg2 2 cerca oeae se: 
“ited ir a re a ce | ‘ad 


| 22 FQMODE 


: 
nn 
enn | 


32 FQDEVN 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


| buffer size inbytes, or0 | sige tn Byes or 0 a 
Ta 
00 
Cini 
[nnn 


0 XRLEN 
2 XRBC 


4 XRLOC 


6 


13 


15 
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XRB+XRLEN The size of the receive buffer, in bytes. This word can be zero 
if no user data is desired on the receive. The amount of data 
transferred from a pending message will never be greater than the 
buffer size. 


XRB+XRBC This word must be passed as zero. The monitor returns the actual 
number of bytes of user data transferred in this word location, as 
shown in the Data Returned sections. 


XRB+XRLOC The starting address of the receive buffer. (See the section "XRB 
(Transfer Request Block)" in Chapter 2 for more information.) 


Data Returned 


The Receive call returns data to the FIRQB and XRB, identifying the type of 
message received and user data, if any, to the buffer defined in the data passed. 


The FIRQB and XRB formats for the local data message follow. 


Data Returned (Local Data Message) 


| FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. 
3 SATII TALL 2 
15 | | 14 FQEXT 
17 | Data passed as parameters by the 16 
sender of this message. | 
21 20 
23 | | 22 
25 : 24 
27 | | 26 
31 | 30 
33 | 32 
35 | 34 
37 | 36 
FIRQB+FQNAM1 A value of 377 means the sender is detached. 
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FIRQB+FQEXT For an EMT logger message, the monitor returns three values: 

e Bytes 14-15 contain the number of data packets not trans- 
ferred. 

e Bytes 16-17 contain the number of EMTs your program 
missed, either because it is not processing data packets 
quickly enough, or because not enough XBUF is available to 
store all the data packets that the monitor is creating. 

e Bytes 20-21 contain the number of data packets transferred. 

See the RST'S/E Programming Manual for more information. 

XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
ELETL ALS ATAL ALP EEL EC 0 
length (actual number of bytes transferred) | 2 XRBC 
| SIT aT 4 
EETLATATA ATE A TET AT SS 6 
11 PITA Tad 10 
13 LIIITEITATIT TTT 12 


Errors 


eg ge Oe Rr OG ge SR OBR ce eR OE Sp Oh ee 


BADCNT The buffer descriptor in the first three words of the XRB is invalid. 


BADFUO Not a declared receiver. Before any receive can succeed, you must execute a 
declare receiver call to define the RIB number you want to use. 


NOSUCH For a receive without sleep (bit 0 in receive modifier = 0), this error indicates 
that no appropriate messages are pending. For a receive with sleep (bit 0 in 
receive modifier = 1), this error is returned when the program is awakened 
from the sleep. The program must execute another receive call to retrieve 
any pending messages. 
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3.16.5 Send Privileges Subfunction 


This subfunction provides a method for a program to tell another program about 
a job’s current privileges and guarantees that the data cannot be falsified. Data 
can be sent at the same time. 


Privileges Required 


SEND to send to a restricted receiver. 


Data Passed - Send Privileges 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 LIITTTITITT TTA TT 0 
3 | LIISA TTT IIT 2 
rasizMs | __ destination | functioncode= 11 | 4 FOFIL 
7 6 FQPPN 
receiver name in ASCII 
11 10 
| (space fill to six bytes) 
13 12 
15 LTTTTT IAAT ET AAT La 14. FQEXT 
| LETITIA TTA TT I 
17 PITTI TTT TTT I 16 
ee POeRregeiageea de fa! 
21 LILIA ATT IA TIT I 20 
LIIITITITT ITI TTT I 
23 LIIIITTITI TITAS T 22 
25 24 
optional user parameter string 
27 26 
(up to 12 bytes of additional 
31 user data can be specified here, 30 
zero fill to 12 bytes) 
33 32 
35 | 34 
37 36 
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FIRQB+FQSIZM 


FIRQB+FQPPN 


Mne- Octal 
monic Offset 


3 


XRB+XRLEN 


XRB+XRBC 


XRB+XRLOC 


You can specify the destination in one of three ways: 


e A zero value indicates that the destination is the receiver 
name that starts at FIRQB+FQPPN. 

e A value equal to the job number times two indicates that 
the destination is this job number. If you do not specify a 
name (FIRQB+FQPPN = 0), the system locates the receiver 
by job number; this works only when the the receiving job 
is receiving messages on RIB 0. If you specify a name, the 
system sends to the specified receiver name. However, the 
system also checks that the receiver’s job number matches the 
value in FIRQB+FQSIZM. 

e A value equal to the local object type (LOT) plus 200 indicates 
that the destination is the receiver for the specified local 
object type number. Only single-instance object types are 
valid (see the RST'S/E Programming Manual). Legal values 
are: 


LOT Receiver 

Error logger 

EMT logger 
PBS—command interpreter 
PBS—server interpreter 
PBS—user request packet 
OPSER 

13 OMS 


Specifies the receiver name. If FIRQB+FQSIZM is zero, this field 


must be nonzero. 


nD oF FR FC ND 


XRB 
Octal Mne- 
Offset monic 


: 
: 
? 


Length of the output buffer, in bytes. This value can range from 
zero through 512. 


The number of bytes to be sent. This value can range from one 
through the size of the buffer, as specified at XRB+XRLEN. If the 
value in XRB+XRLEN is zero, this value must be zero. 


Starting address of the output buffer. (See the section "XRB 
(Transfer Request Block)" in Chapter 2 for more information.) 
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Data Received by Receiver 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | LALIT ITI TT 0 
3 LITTTTTT IITA TTI 2 
FQSIZM5 | job number * 2 function code = -11 4 FQFIL 
11 L///tIIIT/TI sender KB no. or 255 10 FQNAM1 
13 |remainder (number of bytes not transferred) 12 
15 | sender’s privilege mask 14 FQEXT 
17 (4 words) 16 
21 | 20 
23 22 
25 24 
data passed as parameters by 
27 the sender of this message 26 
31 30 
33 32 
34 
37 36 

Errors 

BADCNT The XRB+XRLEN value is illegal. It can range from 0 through 512. 

BADFUO The value at FIRQB+FQSIZM is odd. It must be zero or the receiver’s job 
number times two. 

NOBUFS System buffers are currently not available to store this message for the 
intended local receiver. A later retry may proceed without error. 

NOROOM The number of pending messages for the intended local receiver is at its 
declared maximum, or the receiving job is hibernating. This program should 
try again later. If this error occurs repeatedly, the receiver is not processing 
messages often enough. 

NOSUCH The intended local receiver could not be located in the system’s list of 
declared receivers. The receiver must be declared (with a declare receiver) 
before any data can be transmitted to it. 

PRVIOL Some access violation has occurred. Either the receiver does not allow any 


local senders, or the sender does not have SEND privilege and the receiver 
allows only restricted senders. 
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3.16.6 Create Local LAT Port 


This directive creates a local LAT port for the host to use to initiate LAT 
connections. You can specify the name and unit number of the port to be created; 
if you specify no name, the monitor selects the next available port. The directive 
returns the name and unit number of the local LAT port created in the FIRQB. 
Privileges Required 


SWCTL 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
13 | | TIATIIAAT ET TIP ELT 12 
FIRQB+FQFIL Specifies the SET LAT function. 
FIRQB+FQSIZM Specifies Create Local LAT Port. 
FIRQB+FQDEV Must be the ASCII characters "KB" or zero. If zero, the monitor 
selects the next available port. 

FIRQB+FQDEVN Unit number of the port to be created. 


FIRQB+FQDEVN+1 Must be nonzero. 
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Data Returned 


FIRQB 


Mne- Octal Octal 


monic Offset 


error code or 0 


1 0 
3 2 
5 4 
13 | | 12 
15 14 
17 16 
21 20 
23 22 
25 24 
27 26 
31 "KB" | 30 
FIRQB+0 Error code or zero. 
FIRQB+FQDEV The two ASCII characters "KB". 
FIRQB+FQDEVN Unit number of the port created. 


FIRQB+FQDEVN+1 Nonzero value. 


Errors 


HRRERR 
INUSE 
NOBUEFS 
NODEVC 
PRVIOL 


LAT is not installed on the system. 


The device specified is currently in use. 


Mne- 


Offset monic 


FQDEV 
FQDEVN 


Not enough small buffers are available to create the local LAT port. 


The device specified is not a dynamic keyboard. 
The caller does not have the SWCTL privilege. 
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3.16.7 Delete Local LAT Port 


This directive deletes the local LAT port created by the Create Local LAT Port 
directive. The caller passes the name of the port in the FIRQB. If a session is 
active on the port, the port is deleted once the session has finished. The caller 
can request that the session be terminated immediately by setting the abort bit 
in the flag byte. 


Privileges Required 
SWCTL 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
FQSIZM5 | tdoctal | 4 FQFIL 
7 Fla. | 6 FQPPN 
11 | 10 
13 | 12 
15 14 
17 16 
21 20 
23 22 
25 24 
27 26 
FIRQB+FQFIL Specifies the SET LAT function. 
FIRQB+FQSIZM Specifies Delete Local LAT Port. 
FIRQB+FQPPN The flag byte. If bit zero is set to one, the directive aborts any 
currently active session on the specified port. 
FIRQB+FQDEV Must be the ASCII characters "KB". 
FIRQB+FQDEVN The unit number of the port to be deleted. 


FIRQB+FQDEVN+1 Must be nonzero. 


MESAG—Delete LAT Port 3-115 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


| 


error code or 0 


FALTATASAT ATA AAT TAT 


PALA LTE VIALS A LEE 


PIILTALTAT Flag 6 FQPPN 


10 


EVLA TIAL TAA Aa 
VIAL TE SAAT AALS EA LTT 


12 


14 


| FELT LITTTT TLL PAT aT a 
PITT ETAT TTT AAT AAA 


16 
[niin 


LTT a 


FITIAALILAP EEE TATA 
PELNATALALLAAL TAA ETT 
LITT IIT TTT TI 


PILI IATI ALTA TATA TA ATA 


FIRQB+FQPPN The flag byte. If bit zero is set to one, the port to be deleted has 


an active session. 


20 


22 


24 


26 


30 
32 
34 


36 


Errors 


BADFUO No port name was specified. 

ERRERR LAT is not installed on the system. 

NODEVC The port named is not a local LAT port. 
PRVIOL The caller does not have the SWCTL privilege. 
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3.16.8 Assign a Local LAT Port 


This directive lets the caller specify the server name and the remote LAT port 
name, the remote service name that the port will be assigned to, or both. It also 
lets the user set the default of whether or not requests can be queued. The caller 
must specify the server name as well as the remote port name, the remote service 
name, or both. The directive returns an error if any data is missing. 


Privileges Required 
SWCFG 


Data Passed 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


, 7 
? 2 
11 set defa t flags | ieee default fla ags | 10 FQNAM1 
27 TTT TTT 26 
FIRQB+FQFIL Specifies the SET LAT function. 
FIRQB+FQSIZM Specifies Set Local LAT Port. 
FIRQB+FQPPN Must be zero for Assign Port. 
FIRQB+FQNAMI1 Default settings to clear. If bit seven is set to one, access type is 


set to NOQUEUED. 
FIRQB+FQNAMI1+1 Default settings to set. If bit seven is set to one, access type is set 


to QUEUED. 
FIRQB+FQDEV Must be the ASCII characters "KB". 
FIRQB+FQDEVN The unit number of the port to be mapped. 


FIRQB+FQDEVN+1 Must be nonzero. 
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XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | ionath of Buen an Byise i 0 XRLEN 
3 | 2 XRBC 
5 | 4 XRLOC 
7 6 
11 | 10 
XRB+XRLEN Specifies the length of the buffer. Must not be zero. 
XRB+XRBC Specifies the number of bytes used in the buffer. 
XRB+XRLOC Specifies the starting address of the buffer. The buffer must start 


on a word boundary or an error will be returned. 


The XRB describes a buffer used to pass the remote server, and either the service 
name, the port name, or both. The format of the buffer is: 


Tipe oo] on [yro]ioe] one 
Tine [tow] ont [rvpe]con] one [Woo [ton] one | 


OR 


The buffer has the long format if all three names are used. 


Type A one-byte unsigned value specifying the type of name that 
follows. The valid types are: 


0 remote server name 
1 remote service name 
2 remote port name 


Len A one-byte unsigned value specifying the length of the data field 
that follows. The maximum length is 16 bytes. 


Data The name of the server, service, or remote port. 


The names may contain alphanumeric characters, eight-bit characters with ASCII 
values of 192 to 253 decimal, dollar sign ($), hyphen (-), period (.), or underscore 
(_). Note that spaces are invalid characters. 


Data Returned 


Except for a possible error code in byte 0 of the FIRQB, the assign local LAT port 
directive of MESAG does not return any meaningful data. 
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Errors 


BADCNT 


BADFUO 


BADNAM 
ERRERR 
INUSE 
NODEVC 
PRVIOL 


The length of the fields specified in the user buffer exceeds the length of the 
buffer as given in XRB+XRLEN, or the buffer address was not on a word 
boundary. 


This error can occur for the following reasons: 
An invalid type code was found in the user buffer. 
The remote server, service, or port name length was not in the range of 
1 to 16 decimal bytes. 


The remote server, service, or port had no name specified. 
No local LAT port name was specified. 


The remote server, service, or port name contained invalid characters. 
LAT is not installed on the system. 

The port is currently in use. 

The port named is not a local LAT port. 

The caller does not have the SWCFG privilege. 


-MESAG—Assign LAT Port 3-119 


3.16.9 Deassign Local LAT Port 


This directive lets the caller disassociate the local LAT port from the server it 
was assigned to. Once deassigned, the LAT port cannot be used for host-initiated 
connections until it is once more assigned to a server. 


Privileges Required 
SWCFG 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. : 
3 | | ITLL.” 2 
13 | - UTED TATA TT TELAT AL ELD | 12 
FIRQB+FQFIL Specifies the SET LAT function. 
FIRQB+FQSIZM Specifies Set Local LAT Port. 
FIRQB+FQPPN Must be one for Deassign Port. 
FIRQB+FQDEV Must be the ASCII characters "KB". 
FIRQB+FQDEVN The unit number of the port to be unmapped. 


FIRQB+FQDEVN+1 Must be nonzero. 


Data Returned 


Except for a possible error code in byte 0 of the FIRQB, the deassign local LAT 
port directive of .MESAG does not return any meaningful data. 
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Errors 


BADFUO 
HRRERR 
INUSE 
NODEVC 
PRVIOL 


No local LAT port name was specified. 

LAT is not installed on the system. 

The port is currently in use. 

The port named is not a local LAT port. 

The caller does not have the SWCFG privilege. 
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3.16.10 Return Local LAT Port Status 


This directive lets the caller get current information on the status of the local 
LAT port. The caller must specify the port name of the local LAT port. 


Privileges Required 
No privileges required. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. 
15 PTEHIEPT TTT IATL TTA 1 
FIRQB+FQFIL Specifies the SHOW LAT function. 
FIRQB+FQSIZM Specifies the Show Local LAT Port subfunction. 
FIRQB+FQPPN Must be zero. 
FIRQB+FQPPN+1 Must be one to return status. 
FIRQB+FQDEV The local port name, always the ASCII characters "KB". 
FIRQB_ FQDEVN The local port unit number. 


FIRQB+FQDEVN+1 The unit number real flag. 
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Data Returned 


FIRQB 
Mne- Octal 7 Octal Mne- 
monic OneeE Offset monic 
. . 
, . 
. , 
11 | queue s position | 10 FQNAM1 
ai | 30 FQDEV 
FIRQB+0 Error code or zero. 
FIRQB+FQPPN The port characteristics bit mask. 
Bit Description 
0 Set if application (host-initiated) port 
1 Set if interactive (server-initiated) port 
2 Set if dialup 
7 Set if access type is QUEUED 
FIRQB+FQPPN+1 The status bit mask. 
Bit Description 
0 Set if connected 
1 Set if connection failed 
2 Set if connection in progress 
FIRQB+FQNAM1 Entry position in queue (if bit 2 in Status is 1). 


FIRQB+FQNAMI1+2 RSTS/E error code (if bit 1 in Status is 1). 
Value Meaning 


10 Connection request rejected by server 

16 No response from server 

40 Insufficient resources on this system to initiate a 
connection 
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FIRQB+FQNAM1+3 


FIRQB+FQEXT 
FIRQB+FQDEV 
FIRQB+FQDEVN 
FIRQB+FQDEVN+1 


Errors 


Reject reason code (if bit 1 in Status is 1). The reject reason code 
is returned by the server when a request has been rejected. The 
codes (octal) are defined as follows: 


Value 


IPD oO fF WD DN FH © 


23 


Meaning 

Reason is unknown. 

User requested disconnect. 

System shutdown in progress. 

Invalid slot received. 

Invalid service class. 

Insufficient resources to satisfy request. 
Service in use. 

No such service. 

Service is disabled. 

Service is not offered by the requested port. 
Port name is unknown. 

Invalid password. 

Entry is not in the queue. 

Immediate access rejected. 

Access denied. 

Corrupt solicit request. 

Command type is illegal or not supported. 
Can't send start slot. 

Queue entry is deleted by local node. 


Inconsistent or illegal request parameter. 


Owning job number. 
Local port name, always the ASCII characters "KB". 


Local port unit number. 


Unit number real flag. 


BADFUO No local LAT port name specified. 
HRRERR LAT is not installed on the system. 
NODEVC The port named is not a local LAT port. 
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3.16.11. Return Local LAT Port Characteristics 


This directive lets the caller get information on the current characteristics of the 
local LAT port. The caller must provide a buffer of at least 132 octal bytes. The 
information returned is: 


e Local LAT port name 

e Port type (Application or Interactive) 

e Actual remote server name 

e Actual remort port name 

°e Specified remote server name (Application only) 
° Specified remote LAT port name (Application only) 
e Specified remote service name (Application only) 
e Queued port characteristic 

e Status 

e Queue position 

e Error code 

e Reject reason code 


e Owning job number 


The caller can request information for a specific port by providing the port name 
or by index. When using the index, the caller must specify the port type, which 
determines the list to search for the nth port. The directive returns information 
on only one port at a time. To get information about all local LAT ports of a given 
type, the caller must issue the directive repeatedly, incrementing the index each 
time. When there are not more ports of that type, the directive returns the error 
NOTAVL (ERR=8). An index value of zero means that the port name has been 
provided; the directive then returns information on the named port. If the index 
is zero and no name is provided, the directive returns an error. 


Privileges Required 


None 
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Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


IATITTEIADELAA LS P47 417] 


— 


EEITTIA PALL ELATAT AT 


+14 octal 4 FQFIL 


11 | IITELTIAT | porttype 
emmmiin 
ini 


FQSIZM 5 


: 


6 FQPPN 


10 FQNAM1 


| PITTA TTT Aa 
PETLTI IATL TAG TT a 
PI TTLISLILI DTT ITAA 26 


"KB" 30 FQDEV 


mitnumberfeg | wnitmumber” | $2 ‘FODEVN 


FQDEVN+1 33 


FIRQB+FQFIL Specifies the SHOW LAT function. 
FIRQB+FQSIZM Specifies Show Local LAT Port. 
FIRQB+FQPPN Index value. Zero if port name is specified. 
FIRQB+FQPPN+1 Must be zero to return port characteristics. 
FIRQB+FQNAM1 One of the following port type codes: 

Value Meaning 

0 Specific port requested 

1 Application (host-initiated) port 

2 Interactive (server-initiated) port 
FIRQB+FQDEV Must be the ASCII characters "KB" if index=0. 
FIRQB+FQDEVN The unit number of the local port to be shown if index=0. 


FIRQB+FQDEVN+1 Must be nonzero if index=0. 
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XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


length of buffer, in bytes 


0 XRLEN 
2 XRBC 


starting address of buffer 4 XRLOC 


LE TEETAT ALT TAAL ET TLE Ed 
IAATTTATA TLE ET AAT AL LT 
LVTLELTAIALALLS TTL ELS 


6 


10 
12 


LELTAIAT ATAPI I TTY 14 


XRB+XRLEN Specifies the length of the buffer. Must be at least 132 octal bytes 
long. 

XRB+XRBC Must be zero. 

XRB+XRLOC Specifies the starting address of the buffer. The buffer must start 

on a word boundary or an error will be returned. 


The XRB describes a buffer used to return information to the caller. The buffer 
must be at least 132 octal bytes long. If there is not enough room in the buffer, 


some information will not be returned. The number of bytes actually used in the 
buffer is returned in XRB+XRBC. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. . 
, 
, 
31 | "KB" | 30 FQDEV 
Error code or zero. 
FIRQB+FQPPN The port characteristic bit mask. 
Bit Description 
0 Set if application (host-initiated) port 
1 Set if interactive (server-initiated) port 
2 Set if dialup 
7 Set if the access type is QUEUED 
FIRQB+FQPPN+1 The status bit mask. 
Bit Description 
0 Set if connected 
1 Set if connection failed 
2 Set if connection in progress 
FIRQB+FQNAM1 Entry position in queue (if bit 2 in Status is 1). 


FIRQB+FQNAM1+2 RSTS/E error code (if bit 1 in Status is 1). 
Value Meaning 


10 Connection request rejected by server. 

16 No response from server. 

40 Insufficient resources on this system to initiate a 
connection. 
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FIRQB+FQNAM1+3 Reject reason code (if bit 1 in Status is 1). The reject reason code 
is returned by the server when a request has been rejected. The 
codes (octal) are defined as follows: 


Value Meaning 


0 Reason is unknown. 

1 User requested disconnect. 

2 System shutdown in progress. 

3 Invalid slot received. 

4 Invalid service class. 

5 Insufficient resources to satisfy request. 

6 Service in use. 

7 No such service. 

10 Service is disabled. 

11 Service is not offered by the requested port. 

12 Port name is unknown. 

13 Invalid password. 

14 Entry is not in the queue. 

15 Immediate access rejected. 

16 Access denied. 

17 Corrupt solicit request. 

20 Command type is illegal or not supported. 

21 Can't send start slot. 

22 Queue entry is deleted by local node. 

23 Inconsistent or illegal request parameter. 
FIRQB+FQPFLG Owning job number 
FIRQB+FQDEV Local port name, always the ASCII characters "KB". 
FIRQB+FQDEVN Local port unit number. 


FIRQB+FQDEVN+1 Unit number real flag. 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
: . 
XRB+XRLEN Specifies the length of the buffer. Must not be zero. 
XRB+XRBC Specifies the number of bytes used in the buffer. 
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XRB+XRLOC Specifies the starting address of the buffer. The buffer must start 
on a word boundary or an error will be returned. 


The XRB describes a buffer used to pass additional information about the local 
LAT port. The format of the buffer is: 


The buffer always includes at least two names. For server-initiated connections, 
it contains the names of the actual server and the remote port. For host-initiated 
connections, it contains the name of the specified server and the name of either 
the specified service or the specified remote port. The buffer may also contain 

as many as five names if the port is used for host-initiated connections and is 
connected. 


Type A one-byte unsigned value specifying the type of name that 
follows. The valid types are: 


specified server name 
specified service name 


specified remote port name 


m GC NW Fe 


actual server, if connected 
5 actual remote port, if connected 


Len A one-byte unsigned value specifying the length of the data field 
that follows. The maximum length is 16 bytes. 


Data The name of the server, service, or remote port. 
The names may contain alphanumeric characters, eight-bit characters with ASCII 


values of 192 to 253 decimal, dollar sign ($), hyphen (-), period (.), or underscore 
(_). Note that spaces are invalid characters. 


Errors 


BADCNT Hither the length of the user buffer is zero and the Get Port Information 
form of the SHOW PORT directive was used, or the buffer address is not on 
a word boundary. ie 


BADFUO This error can occur for the following reasons: 
The value in FIRQB+FQPPN was not 0 or 1. 


An invalid port type code was specified. 
No port name was specified with an index value of zero. 


ERRERR LAT is not installed on this system. 
NODEVC The port name specified is not a local LAT port. 
NOTAVL No match for index specified. 
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3.16.12 Show LAT Sessions 


This directive lets the caller get information on the LAT sessions currently active 
on the host node. The caller must provide a buffer of at least 65 octal bytes. The 
information returned includes: 


e The number of the keyboard the user is currently using. 
e¢ The node name of the server the user is on. 


e The name given to the server port the user is on. 


Session information can be accessed in three ways: 
e By index across all servers. 
e By index for a particular server. 


e By keyboard number. 


If no session matches the specified index, the directive returns the error NOTAVL 
(ERR=8). 


Privileges Required 


None 


Data Passed 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


SF$SES (=6) FQFIL 
server name ienath | session index —_| FQPPN 
fies | sender keyboard no. | FQNAM1 
nnn | 


| LATTA ATT 


FQNAM2 


server name, if any, in ASCII 


(FQPPN+1 bytes long) 


FIRQB+FQFIL Specifies the SHOW LAT function. 
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FIRQB+FQSIZM 
FIRQB+FQPPN 


FIRQB+FQPPN+1 


FIRQB+FQNAM1 


FIRQB+FQNAM1 


Mne- Octal 
monic Offset 


Specifies Show LAT Sessions. 


Index value. If there is no session matching this index, the 
directive returns the NOTAVL error. A value of one returns the 
first session. A value of zero means the keyboard number is 


passed in FIRQB+FQNAMI1 


The length of the server name starting at FQNAM2. A non-zero 
value means this is an index lookup by server name. A value of 
zero means that no server is specified and information is returned 
on all servers known to the LAT host node, by index. This byte is 
ignored if FIRQB+FQPPN is zero. 


The keyboard number for which the session information is re- 
turned. This byte is ignored if FIRQB+FQPPN is non-zero. 


If FIRQB+FQPPN+1 is non-zero, then FQNAM2 is the start of 
the name of the server for which session information is returned. 
All lowercase characters in the service name are converted to 
uppercase for comparison. 


XRB 
Octal Mne- 
Offset monic 


5 | | starting address of buffer 7” | 4 XRLOC 
: . 
XRB+XRLEN Specifies the length of the buffer. Must be at least 65 octal bytes 
long. 
XRB+XRBC Must be zero. 
XRB+XRLOC Specifies the starting address of the buffer. The buffer must start 


on a word boundary or an error will be returned. 


The XRB describes a buffer used to return information to the caller. The buffer 
must be at least 65 octal bytes long. If there is not enough room in the buffer, 
some information will not be returned. The number of bytes actually used in the 
buffer is returned in XRB+XRBC. 
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Data Returned 


The data returns in a buffer at most 65 octal bytes long. The number of bytes 
actually used is returned in XRB+XRBC. The buffer contains information on the 
session requested by specific index or by keyboard number. The format of the 
buffer is: | ie | 


Buffer Contents On Return 


1 0 
3 | port name length | 2 
max. 20 octal bytes) | 
server port name 
(length = port name length) 
server node name 
(length = node name length) 
service name length | 
|(max. 20 octal bytes) 
service port name 
(length = service name length) 
Keyboard Number A 1-byte unsigned value giving the number of the 
keyboard on which the session is currently active. 
Port Bitmask A 1-byte bitmask describing the port. 
Bit Description 
0-6 Reserved 
7 Set if the port is a dialup line; otherwise 
clear. 
Port Name Length A 1-byte unsigned value indicating the length, in 


bytes, of the server port name that follows. The 
maximum length of the server port name is 20 octal 


bytes. 

Server Port Name The name of the port on the server on which the user 
is physically connected. 

Node Name Length A 1-byte unsigned value indicating the length, in 


bytes, of the server node name that follows. The 
maximum length of the server node name is 20 octal 


bytes. 
Server Node Name The name of the server on which the user is connected. 
Service Name Length A 1-byte unsigned value indicating the length, in 


bytes, of the service name that follows. The maximum 
length of the service name is 20 octal bytes. 


Service Name The name of the service that the user is currently 
running. 
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Errors 


BADCNT The buffer address is not on a word boundary. 

BADFUO The server name length in FQPPN+1 was larger than 20 octal. 

ERRERR LAT is not installed on this system. 

NODEVC The keyboard number specified at FQNAM1 is not a valid keyboard number. 
NOTAVL No match for the index specified. 

NOSUCH There was no server matching the server specified in the FIRQB. 
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3.17 .NAME — Set Program Name 


Form 
NAME 


Function 


The .NAME directive sets the program name in the monitor tables. The monitor 
enters the name in an internal table; otherwise, it makes no use of the program 
name. However, the SHOW USERS command uses the names in listing current 
information for jobs (under the "What" column) on the system. The BASIC-PLUS 
run-time system uses this directive when the user issues an OLD, NEW, or 
RENAME command. 


The program name is passed as two words of RAD50 data in the FIRQB. Note 
that the data is passed in the same location in the FIRQB where the file name 
exists at the PRUN entry point into a run-time system. If you are coding or 
modifying a run-time system, one of the first things to do on entry at P.RUN is to 
set the program’s name. Thus, the file name’s position in the FIRQB at this point 
is convenient for use. 


Privileges Required 


None 


Data Passed 


FIRQB 


Mne- Octal Octal 


monic Offset 


: : 
: : 
é 
: 
11 | program name in RADS5O foumat | 10 FQNAM1 
(2 words) 
13 12 


Mne- 


Offset monic 


‘NAME 3-135 


FIRQB+FQNAM1 The program name to be set; two words in RAD50 format. 


Data Returned 
The .NAME directive does not return any meaningful data. 


Errors 


No errors are possible with the .NAME directive. 


Example 
The following code sets the name PROGRM in the monitor tables: 


MOV #*RPRO, FIRQOB+FQNAM1 ; Set FIRQB to declare 
MOV #*“RGRM, FIRQB+FQNAM1+2 ; Name of “"PROGRM" 
- NAME 
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3.18 .PEEK — Look at Monitor Memory 


Form 
PEEK 


Function 


The .PEEK directive returns the contents of one word of the monitor’s memory; 
that is, the memory mapped by the kernel mode APRs (see Chapter 2). Only a 
job with the required privileges can execute the .PEEK directive. (However, you 
should not base any of your code on the contents of monitor memory because 
Digital Reserves the right to change the monitor structure and internal addresses 
at any time, except for the addresses listed in Table 3-3.) 


Privileges Required 
RDMEM to read kernel memory other than the I/O page and WRTMEM to read 
the I/O page. 


Data Passed 
XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


virtual address of desired monitor word 


1 0 XRLEN 
87 mmm —_| + 
s[_ mmm _| 4 
[min | 


XRB+XRLEN The virtual address of the data word in monitor memory whose 
contents are to be returned. The value must be even, since word 
addresses on the PDP-11 are always even. Peeking at data in the 
I/O page (kernel APR 7, or 111 (binary) in bits 15, 14, and 13) can 
cause unpredictable system results; Digital does not recommend 
this. Furthermore, using .PEEK to obtain data in APRs 5 or 6 
returns data in the file processor’s private buffer pool. 


Use .PEEK to examine addresses returned by get monitor tables calls or ad- 
dresses of fixed monitor locations. 


Table 3—3 shows fixed monitor locations and their addresses. The RSTS/E 
Internals Manual lists other monitor data structures and their locations in 
memory, but the locations listed in Table 3-3 will not change in future releases of 
RSTS/E. 
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Table 3-3: Fixed Monitor Locations 


Address 
(Octal) Name Meaning 
44(word) IDATE The date when the system was last started by START. 
46(word) ITIME The time of day when the system was last started by 
START. 
1000(word) DATE Current system date. 
1002(word) TIME Current time of day. 
1006(byte) JOB Job number times 2 of the job currently running (always the 
user’s own job number.) 
1010(word) JOBDA Address of the job data block (JDB) of the currently running 
job (always the user’s own JDB). 
1012(word) JOBF Address of the JDFLG word in the JDB of the currently 
running job (always the user’s own JDB). 
1014(word) IOSTS Address of the JDIOST (low) byte and JDPOST (high) byte 
in the JDB of the currently running job (always the user’s 
own JDB). 
Data Returned 
XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. 
. ) 
XRB+XRLEN The contents of the requested monitor memory location. 
Errors 
B.4 The address specified caused a trap to the kernel mode vector at 4 (UNIBUS 
timeout, odd address, and so forth). 
B.250 The address specified caused a memory management unit violation (trap to 


the kernel mode vector at 250). 
PRVIOL The caller does not have the required privilege. 


Example 


The following code obtains the contents of monitor memory location 1006 (the low 
byte of which is the current job number times two): 


MOV #JOB, XRB+XRLEN , Set address to that of "JOB" 
-» PEEK 


3.19 .PLAS — Access Resident Library 


The .PLAS (Program Logical Address Space) directive has six subfunctions that 
allow a MACRO program to access a resident library. Resident libraries must 
be so defined by the system manager with the INSTALL LIBRARY command 
(see the RSTS/E System Manager’s Guide). As noted in Chapter 2, the easiest 
way to do this is to link the resident library to your program using TKB, the 
Task Builder that links modules assembled or compiled under the RSX run-time 
system or its derivatives. However, you can use .PLAS subfunctions to directly 
access resident libraries. 


Table 3-4 lists the .PLAS subfunctions by function code. The following subsec- 
tions describe the subfunctions in alphabetical order. 


Table 3-4: Summary of .PLAS Subfunctions 


FQFUN 
Value 
(Octal) Mnemonic Action Performed 


0 ATRFQ Attach resident library. Attaches the job to a resident 
library; necessary before the job can map a window to the 
library. 
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4 CRAFQ Create address window. Defines a range of virtual addresses 
to be a window for looking at all or some portion of a 
resident library. Optionally, CRAFQ maps the window to 
all or some portion of a resident library. (The mapping can 
be done separately with MAPFQ.) The CRAFQ subfunction 
reserves one or more APRs, so CRAFQ takes space in the 
job area even though the window may not actually be 
mapped. 


6 HLAFQ Eliminate address window. Releases the APRs used by a 
particular window. 


10 MAPFQ Map window. Maps an already created address window of 
virtual addresses to actual memory locations in an attached 
resident library. The monitor loads the library from disk if 
necessary. 


12 UMPFQ Unmap address window. Releases a window of virtual 
addresses from a mapping to actual memory locations. 


When a program exits or a user logs out, the monitor automatically detaches all 
libraries and unmaps and eliminates all windows for the job. 


Privileges Required 


Depends on the subfunction; refer to the individual descriptions that follow this 
introductory information on the .PLAS directive. 
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3.19.1 ATRFQ (Attach Resident Library) 


Form 
MOVB #ATRFQ, FIRQB+FQFIL 


(set appropriate parameters) 


- PLAS 


Function 


The ATRFQ subfunction of .PLAS declares your intent to access a resident library. 
The type of access is specified in the call. The number of resident libraries that 
can be attached to a job at any given time is unlimited (subject to the availability 
of system small buffers). 


The job’s ability to access the resident library depends upon the protection 
assigned to the library by the system manager when the library was installed. 
The default protection grants read access to all users and denies write access to 
all users. 


If the calling job can access the library in the specified fashion, the monitor sets 
up its own internal tables, which lay the groundwork for the job to map windows 
to the library. Note, however, that the resident library does not take up space in 
the job area (virtual memory) with an attach. APRs are assigned (virtual memory 
in the job area is taken) when a window is created (using CRAFQ). 


Privileges Required 


Read-only or read/write access to the library. The protection code is interpreted 
exactly like a file protection code; as with files, access is granted either on the ba- 
sis of the protection code or because of GREAD, GWRITE, WREAD, or WWRITE 
privileges. 
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Data Passed 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


1 LPLIIIIETITII ITI TET TE | oO 
3 | Reeeeleeeeeeee seca ee) 2 
5 | eager. ATRFQ (= 0) 4 FQFIL 
(a LILIITITTIT ITI TT TTT 6 
11 | PETIT IT TAIT TATA TT TT 10 
13 | resident library name in RADS50O format 12 
(2 words) 
15 14 
17 LEEITEIT ETI TIT IAITTT T 16 
21 | PTLTTTA TAT ELIE TATA LILY 20 
25 Peer eceerigereraee ge: | 24 
27 | PEELE IT EIT TIT TTT | 26 
31 PEELE EDAD Le Pee 30 
33 Libdd ddl ld ldddld dd ddd 32 
35 LITEALTATAT TITAS ATT Ed 34 
37 REC eC acerca wererr a ees, 36 
FIRQB+FQFIL The function code ATRFQ (octal value = 0). 
FIRQB+12 The name of the resident library to which the job is to be attached; 
two words in RAD50 format. 
Resident libraries are made known to the monitor by the sys- 
tem manager with the INSTALL/LIBRARY command (see the 
RSTS/E System Manager’s Guide) With this command, the sys- 
tem manager defines a file (filename.LIB) as a resident library. 
The monitor regards "filename" as the-resident library's name. 
FIRQB+FQMODE The low-order two bits of this word define the way the job wants 


to access the library: 
Bit 0 =a Read-only access is desired. 


Bit 1 = ] Read/write access is desired. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


TET TLL 0 
3 | eee “Gurrént job no. ‘2 | 2 FQUOB 
vf | resident ieee identification _ 6 FQPPN 
el “sigerincseword blockec6t neuibrary 1 10 FQNAM1 
13 p Vad tis i11 III! fe 7 | 12 
i] sresessitiititiiiiiit «da 
17 | TITITTTLLLTLLLALALAL -_ | 46 
23 | VITTTT li LM TLALED | 20 
27 | MPLIAIIITIIITIL EE | 26 
33 | i] LITTELLLTLLALAL TTA _ i 32 
35 PPTL” | 34 
FIRQB+FQJOB The current job number times two. 
FIRQB+FQPPN This word is an identifier that must be used, rather than the 


resident library name, in subsequent calls to identify a resident 
library. Thus, you use this identifier to detach the job from the 
library (DTRFQ) and map and unmap windows to the library 
(MAPFQ and UMPF@). 


FIRQB+FQNAMI1 The size of the resident library, in 32-word blocks. 


Errors 


NOSUCH The resident library specified in the data passed is not known to the mon- 
itor. The system manager must install a resident library before it can be 
used. 


PRVIOL The attach did not succeed because the caller’s privilege did not allow the 
access specified in the data passed. This could happen either: 


e Because the access code specified in the data passed is not compatible 
with the possible access defined when the library was installed by the 
system manager. 

e Because the protection code associated with the resident library file 
excludes access by the user. 
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Example 


The following code attaches the job to a resident library called DATBAS. The 
access desired is defined as read/write: 


MOVB #ATRFQ, FIRQB+FOFIL ;DEFINE FUNCTION CODE 
MOV #“RDAT, FIRQB+12 ; LIBRARY NAME IS 

MOV #*“RBAS, FIRQB+FQEXT ;DEFINED AS "DATBAS" 
MOV #2, FIRQB+FQMODE 7; ACCESS=READWRITE 
-PLAS 
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3.19.2 CRAFQ (Create Address Window) 


Form 
MOVB #CRAFQ, FIRQB+FQFIL 


(set up parameters) 


-PLAS 


Function 


The CRAFQ subfunction of .PLAS can be used either to create a window (a 
range of virtual addresses) or to create a window of virtual addresses and map 
it to a range of actual addresses in an attached library. You define the range of 
addresses by: 


e Naming a base APR (which defines the starting address of the window) 
e Specifying the size of the window in 32-word blocks 


Thus, a window always begins on a 4K-word boundary in virtual memory and 
always takes at least 4K words. It may take more than 4K words, depending on 
the size of the window. 


If the required hardware is not present, the CRAFQ fails with an error. 


If the address range overlaps the user job image, the call fails with an error. The 
address range cannot overlap the run-time system (high segment). However, if 
the job is currently running under RSX emulation, this is not a consideration. 
APR 7, normally used to map a run-time system, can be used instead to map a 
window to a resident library. 


The difference between creating a window and creating and mapping a window is 
best shown by example. By using create without map, you can define one window, 
which can be mapped to a library or portion of a library and then remapped to 
another portion of the same library or another library, as many times as desired, 
using the MAPFQ subfunction of .PLAS. 


For example, suppose your program takes up 24K words and you want to access a 
24K-word resident library of data values. You can use create without map to set 
up a 4K-word window in APR 6. You can then map the window (using MAPFQ) 
to the first 4K words of the library, process the data, map to the next 4K words 
of the library, and so forth. If, on the other hand, you had a 4K program and still 
wanted to access a 24K-word library, you could use CRAFQ to create a 24K-word 
window and map it to the entire library in APR 1 to 6. 


A job can create a maximum of seven windows. A window takes at least one APR 
(it may take more, depending on the size you specify for the window). Thus, the 
maximum of seven assumes seven windows in APR 1 to 7. APR 0 can never be 
used to create a window, since the user program takes at least this much space. 
As mentioned previously, a window cannot overlap the user job image; thus, the 
size of the user job image determines the lowest base APR that can be used. If 
the program (user job image) is less than 4K words, APR 1 and up (to the limit 
imposed by the run-time system boundary) can be used to create windows. If the 
user job image is between 4K words and 8K words, APR 2 and up can be used to 
create windows, and so forth. 
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If a window is created that overlaps an already existing window, the old window 
is eliminated. For example, if you create a 6K-word window using a base APR 
of 5, the window uses APR 5 and APR 6. If you then create a 4K-word window 
using a base APR of 6, the entire old window is eliminated. APR 5 is then free 
for other use; APR 6 is used for the new window. 


Privileges Required 


RDMEM to map physical memory other than I/O page read-only. SYSMOD to 
map physical memory read/write or to map the I/O page read/only. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, . 
: ) 
: . 
13 size of windows, in 32-word blocks 12 
35 PTATATAT AT TAL AA A ad | 34 

FIRQB+FQFIL The function code CRAFQ (octal value = 4). 

FIRQB+7 The base APR of the window, 1 to 7. Implicitly defines the starting 
virtual address of the window. This byte cannot be zero; in 
addition, it cannot name an APR already being used to map the 
user job image. 

FIRQB+12 The desired size of the window, in 32-word blocks. For example, a 
value of 128. equals 4K words. 

FIRQB+FQEXT The identifier of the resident library to which the window is to 


be mapped. (This is the value returned by the ATRFQ function 
of .PLAS at FIRQB+FQPPN.) This word is ignored for calls 
requesting a create without mapping (bit 7 at FIRQB+FQMODE 
equals 0). You can also map the window to physical memory by 
passing a value of -4. See MAPFQ for details. 


.PLAS—CRAFQ 3-145 


FIRQB+FQSIZ 


FIRQB+FQBUFL 
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The offset, in 32-word blocks, from the start of the library where 
the mapping is to begin. This word is ignored if no mapping is 
requested (bit 7 at FIRQB+FQMODE equals 0). 


A value of zero for this word indicates the window is to be mapped 
beginning at the first byte of the library. A value of one indicates 
the window is to be mapped beginning at the 33rd word of the 
library (starting address + 64), and so forth. 


The length, in 32-word blocks, of the area to be mapped (ignored if 
bit 7 at FIRQB+FQMODE equals 0). This value cannot be greater 
than the size of the window specified at FIRQB+12. Furthermore, 
this value, combined with the offset value at FIRQB+FQSIZ, 
cannot indicate an address beyond the end of the library or into 
the high segment (run-time system). 


A value of zero for this word defaults to either the size of the 
window (specified at FIRQB+12) or the space remaining in the 
library, whichever is smaller. 


The octal value to set WS.MAP is 200; the value to set WS.WRT is 
2. Thus, an octal value of 202 for this word requests mapping and 
write access. A separate setting for write access in CRAFQ and 
in ATRFQ allows you to attach to a library read/write and map a 
portion of the library read-only. 


If neither WS.UDS nor WS.SIS is set, then CRAFQ uses I-Space, 
and D-Space too if it is available. There is a functional correspon- 
dence between WS.UDS and WS.SIS in the CRAFQ mode byte 
and the region options available in TKB. This correspondence is 
as follows: 


RESCOM & COMMON WS.UDS set 
RESSUP & SUPLIB WS.SIS set 
RESLIB & LIBR neither, WS.UDS and WS.SIS clear 


If WS.UDS = 1, the window is created in the D-Space APR only; 
no mapping in the I-Space is done. If another window is already 
created in both the I- and D- Spaces at this APR, the I-Space 
window remains as it is, but the D window is moved to the 
requested area. If a CRAFQ is done to the same APR with neither 
WS.UDS nor WS.SIS set, the resulting mapping is such that the 
D-Space APR is given to the CRAW with WS.UDS set and the 
I-Space APR is assigned to the region of the second CRAFQ. 


It is illegal to CRAFQ a region with both WS.UDS and WS.SIS 
set. With this directive, supervisor Data Space is always mapped 
the same as user Data Space. See Chapter 5, the section on 


MSDS8$, for information on changing supervisor Data Space under 
RSX. 


Data Returned 


Mne- Octal 
monic Offset 


The octal value to set WS.MAP is 200; the value to set WS.WRT is 
2. Thus, an octal value of 202 for this word requests mapping and 
write access. A separate setting for write access in CRAFQ and 
in ATRFQ allows you to attach to a library read/write and map a 
portion of the library read-only. 


If neither WS.UDS nor WS:SIS is set, then CRAFQ uses I-Space, 
and D-Space too if it is available. There is a functional correspon- 
dence between WS.UDS and WS.SIS in the CRAFQ mode byte 
and the region options available in TKB. This correspondence is 
as follows: 


RESCOM & COMMON WS.UDS set 
RESSUP & SUPLIB WS.SIS set 
RESLIB & LIBR neither, WS.UDS and WS.SIS clear 


If WS.UDS = 1, the window is created in the D-Space APR only; 
no mapping in the I-Space is done. If another window is already 
created in both the I- and D- Spaces at this APR, the I-Space 
window remains as it is, but the D window is moved to the 
requested area. If a CRAFQ is done to the same APR with neither 
WS.UDS nor WS.SIS set, the resulting mapping is such that the 
D-Space APR is given to the CRAW with WS.UDS set and the 
I-Space APR is assigned to the region of the second CRAFQ. 


It is illegal to CRAFQ a region with both WS.UDS and WS.SIS 
set. With this directive, supervisor Data Space is always mapped 
the same as user Data Space. See Chapter 5, the section on 
MSDS$, for information on changing supervisor Data Space under 


RSX. 


FIRQB 
Octal Mne- 
Offset monic 


ETNA TALAL EAL IATA ALA 


EVIE EAL LS current job no. * 2 ‘FQJOB 


/ 


ELT ILA GATT TA TAA A A ED 


LTITIITTT window ID FQPPN 


starting virtual address of new window | FQNAM1 


ETALPA TEAL ELLA TE EAL 
LEE ELIDA LL EC ELL LL 


FPEATAPTTT ALI AIAG ES TT 


_ mapped length, in 32-word blocks FQBUFL 


status flags FQMODE 


PULLIALT AT ELIE LAL LA 


EEELEEAL IAD AL ELT LALLY 


PEALE T ET ITALEST Gee’ 
IP EIIALATA LAL EPIL Al 
PELALAT TALL ALS EPP AL LY 


LELTACLI ALTE PAAL A ET LA 
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FIRQB+FQJOB The current job number times two. 
FIRQB+FQPPN The window ID. Use in later MAPFQ calls to map the newly 


created window; it must be used in any ELAFQ calls to eliminate 
the newly created windows. The value returned may be from 


1 to 7. 
FIRQB+FQNAM1 The starting virtual address of the new window. 
FIRQB+FQBUFL Length actually mapped by the window, in 32-word blocks. 
FIRQB+FQMODE Status flags. The monitor returns the status of the new window 
as follows: 
Bit15 =1 Window was created successfully. 
= 0 Window was not created successfully. 
Bit14 =1 An existing window was unmapped because it 
overlapped the newly created mapping. 
= 0 No existing windows were unmapped by this 
mapping. 
Bit13  =1 An existing window was eliminated because it 
overlapped the newly created window. 
= 0 No existing windows were eliminated by this 
create. 


Errors 


BADFUO 


NOBUFS 


NOROOM 
NOSUCH 


PRVIOL 


Example 


Hither the base APR and window length specified were invalid, or the offset 
and mapping length values specified were invalid. (For example, an offset 
indicating a starting address for the mapping that is beyond the end of the 
library or into the run-time system is invalid.) 


Creating a window requires a small buffer; a small buffer is not currently 
available. 


You attempted to create more than seven address windows. 


The library ID specified for mapping is not a library currently attached to 
the job. 


The create was unsuccessful because the user privileges do not allow the ac- 
cess desired. At this point, since the library has been attached successfully 

with some access defined, this error means that the access requested in the 

CRAF@Q is not allowed by the access requested in the ATRFQ. 


The following code creates a 4K-word address window and maps it to the begin- 
ning of a library whose ID (returned from a previous ATRFQ) has been stored at 


location LIBID: 

MOVB #CRAFQ, FIRQB+FQFIL ;DEFINE FUNCTION CODE 

MOV #6, F IRQB+7 ;BASE APR = 6 

MOV #200, FIRQB+12 ;WINDOW = 4K WORDS 

MOV LIBID, FIRQB+FQEXT ;SET LIBRARY ID 

CLR FIRQB+FOSIZ ;OFFSET = 0 

CLR FIRQB+FQBUFL ;MAP 4K WORDS OR TO 
;END OF LIBRARY 

MOV #200, FIRQB+FQMODE ;MAP WINDOW, READ-ONLY 

.PLAS 
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3.19.3 DTRFQ (Detach Resident Library) 


Form 
MOVB #DTRFOQ, FIRQB+FOFIL 


(define library to be detached) 


-PLAS 


Function 


The DTRFQ subfunction of .PLAS detaches a previously attached resident library. 
Any windows mapped to the library by the calling job are unmapped. If no other 
jobs are currently attached to the library and it was installed with the /UNLOAD 


option, the monitor removes the library from memory. 


If this is a dynamic region and there are no other jobs currently attached to it, 
and the region is marked for deletion after the last job detaches, the monitor 
removes the region from memory and deletes it from the resident library list. 


Privileges Required 


None 


Data Passed 


FIRQB 


Mne- Octal Octal 
monic Offset Offset monic 


FATAATALAT ATL AP Pad il 


| ETALEL TAAL AAD ED LAL 


YA DTRFQ (= 2) 


library identification (returned by ATRFQ) 


LEST ELT ALLAETA AT ETI Ge 


Cece Cesserer erent ss, 


LEEE EA PITALT AAT LAL ILLS 
VALET SG AL AAAT AAT AE IL ALS! 


[rime 


PIGITETATELAT IAAL AE EET 


VALID TALIA EA ALAPEL AG | 


0 


2 


Mne- 


4 FQFIL 


6 FQPPN 


10 


12 


14 


16 


20 


22 


24 


26 


30 


32 


34 


36 
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FIRQB+FQFIL The function code DTRFQ (octal value = 2). 


FIRQB+FQPPN The library identification returned at FIRQB+FQPPN by the 
ATRFQ that attached the job to the library. 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 LPIA ALATA TAA Tadd ddd 0 
. , 
; ) 
23 | | _ status fla |} 22 FQMODE 
FIRQB+FQJOB The current job number times two. 
FIRQB+FQMODE Bit 14 of this word is set if any windows were unmapped as a 


result of this detach. 


Errors 


NOSUCH The library ID specified at FIRQB+FQPPN in the data passed does not 
identify any library currently attached to the job. 


Example 
The following code detaches the library whose ID is stored at LIBID: 


MOVB #DTRFQ, FIRQB+FQFIL 7;SET FUNCTION CODE 
MOV LIBID, FIRQB+FOQPPN ;SET LIBRARY ID 
-PLAS 
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3.19.4 ELAFQ (Eliminate Address Window) 


Form 


MOVB #ELAFQ, FIRQB+FQFIL 
(set up parameters in FIRQB) 


»-PLAS 


Function 


The ELAFQ subfunction of .PLAS eliminates an address window that was created 
by the job, unmapping the window if necessary. ELAFQ frees the APRs used 

by the window and makes them available for creating another window or for 
expanding the user job image size. 


Privileges Required 
None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LIL ELT TELAT TIA EE ELE LET 


Treen | naw 


BLEELTIACTA TET AA TT LY 
LIPTILITAAT TEL II PATA 


0 

2 

4 FQFIL 
6 FQPPN 


10 


12 


14 


16 


20 


22 


LELEALAALT ST EP LIS LAL | 
LALA PATE CETAL EL ALATA 24 


PIII TIIIII ITI TIT 26 


30 


32 
34 


36 


FIRQB+FQFIL The function code ELAFQ (octal value equals 6). 
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FIRQB+FQPPN The ID of the window to be eliminated (returned at FIRQB+FQPPN 
by the CRAFQ that created the window). 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. , 
: . 
25 | ee eet 24 
FIRQB+FQJOB The current job number times two. 
FIRQB+FQMODE Two bits in this word indicate the status of the window: 
Bit13 =1 The window was successfully eliminated. 
= 0 The window was not eliminated. 
Bit14 =1 The address window was mapped to a resident 


library and has been unmapped. 


= 0 The address window was not mapped; no unmap- 
ping was done. 


Errors 


BADFUO An invalid window ID was given in the data passed at FIRQB+FQPPN 
(outside the range 1 through 7). 


NOSUCH The window ID specified at FIRQB+FQPPN is in the range 1 through 7 but 
matches no currently created window for this job. 
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Example 


The following code eliminates an address window whose ID is stored in location 
WINID: | | 


MOVB #ELAFQ, FIRQB+FQFIL ;SET FUNCTION CODE 
MOVB WINID, FIRQB+FOQPPN ;SET WINDOW ID 
»~PLAS | 
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3.19.5 MAPFQ (Map Address Window) 


Form 
MOVB #MAPFQ, FIROB+FOFIL 


(set up parameters) 


» PLAS 


Function 


The MAPFQ subfunction of .PLAS maps a previously created address window 
to an attached resident library. In other words, the MAPFQ relates the virtual 
address range defined by a CRAFQ to actual locations in memory within a 
resident library that has been attached to the job by an ATRFQ. MAPFQ maps 
the window in the address space given by the CRAFQ, supervisor I-Space, user 
I-Space, or user D-Space. | 


If the window specified is already mapped, it is unmapped from its previous 
actual memory locations and remapped to the new area. A job may map a 
maximum of seven address windows at any given time. 


If the resident library being mapped is not in memory when the MAPFQ is 
executed, the system makes the library memory resident at that time. 


Privileges Required 


None, except to map physical memory (see the section "Map Physical Memory"). 
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Data Passed 


Mne- Octal 
monic Offset 


FIRQB 


Octal Mne- 
Offset monic 


1 ; O 

3 | VALLETTA DAALT AAP TAL TT | 2 

5 | LT ili | MAPFQ ( =10) 4 FQEFIL 
7 LETT TY | window ID 6 FOPPN 
11 | FIATTT EET ITI ALA ETL LT ; 10 

13 | OTT ae 12 

15 | resident library ID 14 FQEXT 
17 offset, in 32-word blocks | 16 FQSIZ 
21 | length, in 32-word blocks, to be mapped | 20 FQBUEFL 
25 | TAL VELLA PT TLE LETTE ET 24 

2/7 FLEPELIT IVA TATA TAS 26 

31 | LES TT TTT PITT 30 

33 LALEERAL IPI ATE TEAL Fa | 32 

35 TALAA ELTA ALAA LA ELA C4 34 

37 VLEET IA PALA PLATT EY 36 

FIRQB+FQFIL The function code MAPFQ (octal value equals 10). 

FIRQB+FQPPN The ID of the window to be mapped (returned at FIRQB+FQPPN 
by the CRAFQ subfunction call that created the window). The 
window ID can be for any current window that uses some D-Space; 
it cannot refer to a window using only I-Space. 

FIRQB+FQEXT The ID of the resident library to which the window is to be 
mapped (returned as a full word at FIRQB+FQPPN by the ATRFQ 
subfunction call that attached the job to the resident library). 

FIRQB+FQSIZ The offset from the start of the library where the mapping is to 
begin, in 32-word blocks. 

A value of zero for this word indicates the window is to be mapped 
beginning at the first byte of the library. A value of 1 indicates 
that the window is to be mapped beginning at the 33rd word of 
the library (starting address = 64), and so forth. 

FIRQB+FQBUFL The length of the area to be mapped, in 32-word blocks. This 


value cannot be greater than the size of the window (speci- 

fied at FIRQB+12 in the CRAFQ which created the window). 
Furthermore, this value, combined with the offset value at 
FIRQB+FQSIZ, cannot indicate an address beyond the end of 

the library. 

A value of 0 for this word defaults to either the size of the window 
specified in FIRQB+12 in the CRAFQ or the space remaining in 
the library, whichever is smaller. 
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FIRQB+FQMODE Bit 1 of this word specifies whether the window is to be mapped 
read/write or read-only: 


Bit 1 =] Read/write access. 
= Read-only access. 


A separate setting for access in MAPFQ and in ATRFQ allows you 
to attach to a library read/write and map a portion of the library 
read-only. You cannot, however, attach to a library read-only and 
then map to the library read/write. 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


current job no. 
inn 
CT 
Prrerneenenin d 
CT 
erence 


FIRQB+FQJOB The current job number times two. 
FIRQB+FQBUFL Length actually mapped by the call, in 32-word blocks. 


FIRQB+FQMODE Bit 14 of this word is a status flag: 


Bit14 =1 The window specified was already mapped; the 
window was unmapped before this mapping was 
done. 


0 


2 FQJOB 


4 


6 


10 


12 


14 
16 
20 FQBUFL 
22 FQMODE 
24 
26 
30 
32 
34 


36 


=0 The window specified had no previous mapping; 
no unmapping was done for this call. 
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Errors 


BADFUO The offset and length specified are inconsistent; either the mapping at- 
tempted to go beyond the end of the library or the length is greater than the 
created window. 

NOSUCH Either the resident library ID or the address window ID is incorrect. (The 
job is not currently attached to the specified resident library or no address 
window has been created with the specified window ID.) 


Example 


The following code maps a window whose ID is stored at WINID to the attached 
library whose ID is stored at LIBID. The offset of 256 indicates that the mapping 
is to begin 8K words from the start of the library. Access to the library is read- 
only. For example: 


MOVB #MAPFQ, FIRQB+FOFIL ;SET FUNCTION CODE 

MOVB WINID, FIRQB+FQPPN ;SET WINDOW ID 

MOV LIBID, FIROB+FQEXT ;SET LIBRARY ID 

MOV #256.,F IRQBt+FQOSI2 ;OFFSET 8K WORDS 

CLR FIRQB+FQBUFL ;MAP WINDOW SIZE OR 
;TO END OF LIBRARY 

CLR FIRQB+FQMODE ;READ-ONLY ACCESS 

»PLAS 


Map Physical Memory 


You can also use MAPFQ to map a window to physical memory. The data passed 
is the same as for a resident library except FIRQB+FQEXT contains -4. The data 
returned is the same. 


You can map to monitor memory, XBUF, user memory, and so on, but not to 
locked memory (including virtual disk), or non-existent memory. If you try to map 
to locked or non-existent memory, you get a privilege violation error. 


Privileges 


You need RDMEM to map read/write or read-only. You need SYSMOD to map 
read/write. If the starting address in memory is 17760000 or higher (block 
number 177600), you also need SYSMOD for read-only. 
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Data Passed (Map Physical Memory) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 LIIIIITIITI AAAI AA Td 0 
3 LTT ATA TIA FAT a aa aT i 2 
5 TIMI | MAPFQ ( =10) 4 FQFIL 


12 

FQEXT 

FQSIZ 

FQBUFL 

FQMODE 
FIRQB+FQFIL The function code MAPFQ (octal value equals 10). 
FIRQB+FQPPN The ID of the window to be mapped (returned at FIRQB+FQPPN 

by the CRAFQ subfunction call that created the window). 

FIRQB+FQEXT 4 to indicate map to physical memory. 
FIRQB+FQSIZ The offset from the start of memory where the mapping is to 


begin, in 32-word blocks. 


A value of zero for this word indicates the window is to be mapped 
beginning at the first byte of physical memory. A value of 1 
indicates that the window is to be mapped beginning at the 33rd 
word of physical memory (starting address = 64), and so forth. 


FIRQB+FQBUFL The length of the area to be mapped, in 32-word blocks. This 
value cannot be greater than the size of the window (speci- 
fied at FIRQB+12 in the CRAFQ which created the window). 
Furthermore, this value, combined with the offset value at 
FIRQB+FQSIZ, cannot indicate an address beyond the end of 
physical memory. 


A value of zero for this word defaults to either the size of the 
window or the space remaining in physical memory, whichever is 
smaller. 
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FIRQB+FQMODE 


Errors 


Bit 1 of this word specifies whether the window is to be mapped 
read/write or read-only: 


Bit 1 =] Read/write access. 
= 0 Read-only access. 


You need SYSMOD privilege to map read/write. You need 
RDMEM privilege to map either way. If you want to map the 

V/O page by specifying a starting address of 17760000 or higher 
(block number 177600), you need SYSMOD privilege to map either 
way. 

You can map to monitor memory, XBUF, or user memory, but not 
to locked memory (including virtual disk), or nonexistent memory. 


PRVIOL The mapping was unsuccessful because user privileges did not allow the 
access desired or you attempted to map to locked or nonexistent memory. 


3.19.5.1 Fast-Mapping Facility 


You may want to use the fast-mapping facility instead of the MAPFQ subfunction. 
It enhances performance and is compatible with the fast-mapping facility of 
RSX-11M-PLUS. The RSTS/E RSX emulator also provides the following features: 


e The Task Builder /FM switch. 


e The TFEA$ RSX monitor call can tell a program if fast-mapping is enabled. 
¢ The .SET and .CLEAR monitor calls allow a task to enable and disable 


fast-mapping. 


You can use fast-mapping if your program does not use any IOT instructions 
except to perform the fast-map operations. To use the fast-mapping facility, 
set parameters as shown in the following calling sequence, then issue an IOT 


instruction: 


Calling Sequence 


RO parameter 1 
Rl parameter 2 
R2 parameter 3 


see table of APR parameter values 
offset field, 32 decimal words from library base 
optional length specification (if used, bit 15 in RO 


must =1) 


LOT 


Returned Data 
RO Status 


R2 length mapped 
Rl & R3 


calls the monitor to execute mapping 


IS.SUC if successful 

IE.TIS or IE.ALG if unsuccessful 

if successful length actually mapped in slivers 
indeterminate | 
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Table of Parameter Values 


Base If No Length ae 
Space APR Given Given 
User-I 0 APR I-0 cannot be changed 
User-I 1 000010 100010 
User-I 2 000020 100020 
User-I 3 000030 100030 
User-I 4 000040 100040 
User-I 5 000050 100050 
User-I 6 000060 100060 
User-I it 000070 100070 
User-D 0 APR D-0 cannot be changed 
User-D 1 000110 100110 
User-D 2 000120 100120 
User-D 3 000130 100130 
User-D 4 000140 100140 
User-D 5 000150 © 100150 
User-D 6 000160 100160 
User-D 7 000170 100170 


The fast-mapping facility has the following restrictions: 


e The fast-mapping facility can modify only the map field (FQSIZE) and, 
optionally, the length to the map field (FQBUFL). 


e The interface to the fast-mapping facility is designed for speed, not for ease of 
programming. It may be harder to debug a task using fast-mapping than one 
using the .PLAS directive. The only validation fast-mapping does is to protect 
the operating system and its data structures 


e The interface uses the IOT instruction. Tasks that use fast-mapping cannot 
use the IOT instruction for any other purpose. 


e The interface uses registers to pass parameters instead of using a FIRQB. 
This means that the MACRO-11 programmer must be careful about register 
use when fast-mapping. 


Examples 


Change the window offset in an I-Space library: 


MOV #60, RO ;I-Space window in APR 6 

MOV #200,R1 ;offset 4K words from the beginning of library 
-R2 not used 

TOT z;do the re-map 

TST RO yany errors? 

BMI ERROR ;if minus yes, otherwise ok 


Change the D-Space window offset and the actual window length: 


MOV #100150, RO ;D-Space window in APR 5, length to be given 
MOV #400,R1 ;offset 8K words from library base 

MOV #500,R2 ;length to be 10K words (use APR 5,6 &7) 

IOT yissue instruction 

TST RO jany errors? 

BMI ERROR ;if minus yes, otherwise ok 
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3.19.6 UMPFQ (Unmap Address Window) 


Form 
MOVB #UMPFOQ, FIRQB+FQFIL 


(set up parameters) 


-PLAS 


Function 


The UMPFQ subfunction of .PLAS unmaps a specified address window from a 
resident library. (Note that a MAPFQ on an already mapped window unmaps the 
existing windows. ) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


: 
, 
LITT TELTT | window ID 6 FOPPN 


LALALA LAT PLATE THEY Coed 10 


PLLA LELTIA LE PAT ESA A 


12 


CL TAACHLELT LIA ALLL ELA 14 
ELA TVETIAT TIA TEAL A 16 
LAPP A PLL EEE EEE ELLA 20 


TATASAT ADEA LPL LET TA 22 


PETTITT ELATETE TAPIA LATS 24 
IIIIITEIII TITTY TTT i 26 


: 
: 
: 


FIRQB+FQFIL The function code UMPFQ (octal value equals 12). 


FIRQB+FQPPN The ID of the window to be unmapped (returned at FIRQB+FQPPN 
by the CRAFQ that created the window). 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 PETAL A A TAGAEEET ATE EET 0 
3 re, 2 FQJOB 
semi] « 
iin | 6 
21 HITT I ELELLT / / | | a 20 
31 EELTAALAAPAL EEA TALI 30 


FIRQB+FQJOB The current job number times two. 
FIRQB+FQMODE Bit 13 of this word is set if the unmapping was successful. 


Errors 


BADFUO The window ID specified is invalid (not in the range 1 to 7). 


NOSUCH The window ID specified is in the range 1 to 7, but no such window is 
currently created for the job. 


Example 


The following code unmaps the window whose ID is stored at WINID: 


MOVB #UMPFQ, FIRQB+FQFIL ; SET FUNCTION CODE 
MOVB WINID, FIRQOB+FQPPN 
»PLAS 
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3.20 .POSTN — Return Current Horizontal Position 


Form 
.POSTN 


Function 


The .POSTN directive returns the maximum line width and the current horizon- 
tal position of devices for which this information is relevant (line printers and 
terminals). Data is passed in the XRB defining the channel where the device is 


currently opened. The information is returned in the XRB. 
Privileges Required 


None 


Data Passed 


XRB 
Mne- Octal Octal Mnhne- 
monic Offset Offset monic 


XRB+XRCI Channel number times two; defines the channel on which the file 


or device is open. 


Data Returned 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


current position 


0 XRLEN 


2 XRBC 


-POSTN 


3-163 


XRB+XRLEN The file or device’s maximum line length plus one. For example, a 
value of 81. would indicate a maximum line length of 80. bytes. 

XRB+XRBC The file or device’s current horizontal position is returned here. 
The value can range from zero (leftmost character) to the value 
returned at XRB+XRLEN minus one (rightmost character). If the 
device does not keep track of its own horizontal position, then 
this value is zero. The FLGPOS status bit returned in the FIRQB 
when the file or device was opened indicates whether the value 
returned here is meaningful. 


Errors 


NOTOPN No file or device is open on the specified channel. 
DETKEY The device is a terminal that is detached. 


Example 

The following code requests the current horizontal position of the device open on 
channel 4: 

MOVB #4*2, XRB+XRCI ;SET CHANNEL TO 4 

. POSTN 
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-READ — Read Data from File or Device 


Form 
-.READ 


Function 


The .READ directive reads data from a file or device previously opened on a 
channel. The amount of data read depends on the device and the size of the 
buffer area, as defined in the XRB. The number of bytes transferred is always 
less than or equal to the buffer size. The actual number of bytes read is returned 
in the XRB when the directive is complete. Specific details for each device are 
given in Table 3—5. The "best guess" buffer sizes (returned by the monitor at 
FIRQB+FQBUFL when the device was opened) are also shown, for comparison. 


When you do I/O to or from a resident library mapped in D-Space, such as a 
dynamic region, you can use I/O buffer sizes larger than the greatest size that 
can be mapped into the program’s virtual address space. You can get single I/O 
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use 
such large block sizes. 


You only need to map the first word of the I/O buffer into the the virtual address 
space, so the monitor can locate the buffer in the resident library. However, the 
entire buffer must reside in the resident library; otherwise, the monitor rejects 
the I/O request. This feature is available only for resident libraries mapped in 
D-Space. 
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Table 3-5: Data Input with .READ 


What Happens When 
"Best 
Block Guess," -READ’s Buffer Size 
Size, Bytes Bytes Intent to >= Intent Buffer Size 
Device (Decimal) (Decimal) Deliver < Intent 


Byte-Oriented Devices (FLGFRC=1, FLGRND=0) 


Keyboard N/A 128 1 line ! 1 line ! Fill buffer; next .READ 
(Terminal) reads next part of line. 
Pseudo N/A 128 Full buffer N/A N/A 

Keyboard | 

Paper Tape N/A 128 Full buffer N/A N/A 

Reader 

Card Reader N/A 160 1 card 1 card Fill buffer;next .READ 


reads next part of card. 


Block-Sequential Devices (FLGFRC=0, FLGRND=1) 


Magnetic 18 to 32,767 512 1 block 1 block Fill buffer; next .READ 

Tape starts with new block. 
(Error returned.) 

DECtape 510 510 1 block 1 block Fill buffer; next .READ 

(file- starts with new block. (No 

structured) error returned.) 

DMC/DMR 1 to 632 512 1 message 1 message Delivers partial message. 
Next .READ delivers next 
message. 


Block-Random Devices (FLGFRC=0, FLGRND=0) 


Disk 18 to 32,767 512 Full buffer Fills buffer; next .READ starts with new 
block. ” 

Flexible 512 Full buffer Fills buffer; next .READ starts with new 

Diskette block or sector. ” 

DECtape 512 512 1 block 1 block Fill buffer; next READ 

(non-file- starts with new block. (No 

structured) error returned.) 


1A line is any number of characters terminated by RETURN, LINE FEED, ESCAPE, FORM FEED, Ctrl/Z, Ctrl/D, 
Ctrl/C, or a user-set private delimiter. 

2If the buffer size is not a multiple of the blocksize, the remainder of the last block is not read. The next .READ starts 
with a new block: either the next sequential block (CRB+XRBLK=0) or the nth block (XRB+XRBLK=n). No error is 
returned. 

3512 (block mode) or 128 (RX01 or RX02 single-density sector mode) or 256 (RX02 double-density sector mode) 


Privileges Required 


None 
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Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


XRB+XRLEN The length of the input buffer, in bytes. This word must be 
nonzero. The amount of data read depends on both the device 
and the buffer size. However, the amount of data is never more 
than the buffer size. See Table 3-5 for details on reads for specific 


devices. 
XRB+XRBC This word must be passed as zero. The monitor returns the actual 


number of bytes transferred in this word location (see the Data 
Returned section). 


XRB+XRLOC The starting address of the buffer. For disk, flexible diskette, and 
magtape devices, this address must be on a word boundary. For 
all other devices, the buffer can begin on an odd address. (See 
the section "XRB (Transfer Request Block)" in Chapter 2 for more 
information. ) 


XRB+XRCI Channel number times two; defines the channel for the read, 
as previously defined in an open (OPNFQ, CRTFQ, CREFQ, or 
CRBFQ functions of CALFIP). 


XRB+XRBLKM For files on disk, this byte contains the MSB of the block number 
to begin the read. This byte is combined with the word at XRBLK 
to form a 24-bit field defining the block number. This byte is 
ignored for nondisk devices. 


XRB+XRBLK For channels opened as file-structured, this word defines the 
starting block number for this read. (For large files, this word 
forms the LSB of the block number to start the read.) The value 
performs the same action as the BLOCK option for disk and 
the RECORD option for flexible diskette and non-file-structured 
DECtape (see the RSTS/E Programming Manual). Note that this 
word is ignored if the device is not a random-access device. 


If the device is random-access and this field is nonzero, it is 
interpreted as the block number where the read is to start (1 to n, 
where n is the length of the file, in 512-byte blocks). If the field 
is zero, the next sequential block is read. For example, if a disk 
file is being read with a 1024-byte buffer size, a .READ with this 
parameter equal to four would cause the fourth and fifth blocks of 
the file (512 bytes each) to be read into the buffer. 
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XRB+XRTIME 


XRB+XRMOD 


Data Returned 


Mne- Octal 
monic Offset 


For channels opened on disk as non-file-structured MODE 0, this 
word defines the device cluster number where the read is to begin. 
In this case, each .READ begins with a new device cluster, so the 
buffer size at XRB+XRLEN should be a multiple of the device 
cluster size. 


If positive, the maximum time to wait for terminal input data, in 
seconds. Zero indicates an infinite wait. A negative value (bit 15 
equals 1) indicates an infinite keyboard monitor wait. This wait 
is used by run-time systems that act as keyboard monitors for 
their command input. This type of wait time acts as a flag to the 
monitor and to the batch subsystem that the job is in a command 
input wait state. 


Input operation modifier; significant only for card reader, terminal, 
DMC/DMR, or paper tape devices. (The monitor informs you with 
the FLGMOD bit of the flag word returned at FIRQB+FQFLAG 
on the open whether or not the device accepts modifiers.) This 
parameter performs the same action as the RECORD modifier in 
BASIC-PLUS for these devices (see the RSTS/E Programming 
Manual). 


XRB 
Octal Mne- 
Offset monic 


1 Pane eee a rae ae eae a em a: 0 
3 actual number of bytes read 2 XRBC 
5 ELTETALTAL AAT AA ET ad a 4 
XRBLKM7 MSB of block number I/II tIITTT 6 
11 LSB of block number where .READ began 10 XRBLK 
13 FAT LTALI TL SALT AT IATA TY 412 
15 | PPLIETTATTT TT TAT 14 
XRB+XRBC Actual number of bytes just read. The value is between zero 
and the value of XRB+XRLEN passed in the XRB. If an error is 
returned on the read (as indicated by byte 0 of the FIRQB), this 
word may or may not be zero. That is, data may be input even if 
an error occurs. For example, if the card reader detects an illegal 
card column punch combination, it places the decoded card data 
in the input buffer, substituting a special character for the bad 
column. The XRB+XRBC field is correctly set for the number of 
characters input, and an error is returned. 
XRB+XRBLKM For disk files, this byte contains the MSB of the block number just 
read. (See XRB+XRBLE.) 
XRB+XRBLK For random-access devices (see Table 3-5), this word contains 


the block number of the block just input with this .READ. Block 
numbers range from 1 to n (where n is the length of the file, 

in 512-byte blocks); they define the order in which the file was 
written. (For disks opened non-file-structured MODE 0, this is the 
device cluster number.) 


Errors 

The possible device-independent errors are: 

BADCNT The first three words of the XRB describing the input buffer are illegal. 
(Illegal byte count for I/O.) 

BSERR The specified channel number is illegal. 

NOTOPN No file or device is open on the specified channel number. 

PRVIOL The file or device open on the specified channel is write-only, or the caller 
did not obtain read access to the file or device when it was opened. 


All other errors are device-dependent. Some common errors are: 


DATERR Some data error occurred. There may or may not be any valid data in the 
input buffer. This error is issued for parity errors, bad card columns, and so 
on. 

HNGDEV Some hard device I/O error occurred. There is usually no data in the input 


buffer when this error occurs. (For example, a .READ for an off-line device 
causes this error.) 


Example 


In this example, we assume that a disk file has been opened on channel 2. 
Space for the buffer is allocated with the .BLKB directive, and the buffer size 
and location are defined. The next sequential block in the file is to be read 
(XRB+XRBLEK is zero). 


BUFFER: - BLKB 512. | ; ALLOCATE SPACE FOR BUFFER 
CALL CLRXRB 
MOV #512.,XRB+XRLEN ;SET BUFFER SIZE TO 512. BYTES 
MOV #BUFFER, XRB+XRLOC ; STARTING ADDRESS OF BUFFER 
MOVB #2*2,XRB+XRCI ;CHANNEL 2 FOR INPUT 
-» READ 
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3.22 .READA—Read Data from a Device (Asynchronous) 
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Form 
.READA 


Function 


The asynchronous read directive (.READA) performs the same basic functions 
as the synchronous read directive (.READ): both move data between a device 
and a user program. The difference lies in the completion of the request. While 
synchronous read requests stall the job’s execution until the request completes, 
asynchronous read requests do not stall; the program continues to run while the 
I/O request completes in parallel with program execution. The mechanism that 
the RSTS operating system uses to notify the user job upon I/O completion is an 
asynchronous completion routine. 


When you do I/O to or from a resident library mapped in D-Space, such as a 
dynamic region, you can use I/O buffer sizes larger than the greatest size that 
can be mapped into the program’s virtual address space. You can get single I/O 
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use 
such large block sizes. 


You only need to map the first word of the I/O buffer into the the virtual address 
space, so the monitor can locate the buffer in the resident library. However, the 
entire buffer must reside in the resident library; otherwise, the monitor rejects 
the I/O request. This feature is available only for resident libraries mapped in 
D-Space. 


Privileges Required 


TUNE is required to perform multiple asynchronous read functions. 


Data Passed 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


1 LEIA TTT III IPT IAA 0 
3 VIAL NED AED aiS, 2 
5 Completion Routine Radiess 4 FQFIL 
7 eee supplied Peremeter 6 FQPPN 
11 TATTLE TAT 10 
13 ALITTLE 12 
15 AEE TE MET POLE 14 
17 TTT 16 
21 TTT 20 
23 PTTL TTT TTT LTLTT 22 
25 TTT TT LTTTET 24 
27 PEE EEE RC ee 26 
31 TT 30 
33 ee ee ogee 32 
35 ALTE LTT 34 
37 EL PAT ATL ALATA LAL TAGS 36 
FIRQB+FQFIL Identifies the address in the user job where program flow should 
begin when the asynchronous read completes. If FIRQB+FQFIL 
is zero, no AST completion routine is executed. In this case, it 
is understood that the user is using some other mechanism to 
determine whether the I/O request has successfully completed. 
FIRQB+FQPPN This field is used by the user job to communicate informa- 
tion to the AST completion routine with the user’s program. If 
FIRQB+FQFIL is zero, this value is ignored. 
XRB 
Mne- Octal Octal Mne- 


monic Offset 


cise! monic 


11 LSB of block HUIS! to begin (0 = next) | 10 XRBLK 
13 wait time for terminal pe 12 XRTIME 
15 device-dependent modifier 14 XRMOD 
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XRB+XRLEN 


XRB+XRBC 


XRB+XRLOC 


XRB+XRCI 


XRB+XRBLKM 


XRB+XRBLK 


XRB+XRTIME 


XRB+XRMOD 


The length of the input buffer, in bytes. This word must be 
nonzero. The amount of data read depends on both the device and 
the buffer size. However, the amount of data can never be more 
than the buffer size. See Table 3—5 for details on reads for specific 
devices. 


This word must be passed as zero. The monitor returns the actual 
number of bytes transferred in this word location (see the Data 
Returned section). 


The starting address of the buffer. For disk, flexible diskette, and 
magtape devices, this address must be on a word boundary. For 
all other devices, the buffer can begin on an odd address. (See 
the section "XRB (Transfer Request Block)" in Chapter 2 for more 
information.) 


Channel number times two; defines the channel for the read, 
as previously defined in an open (OPNFQ, CRTFQ, CREFQ, or 
CRBFQ functions of CALFIP). 


For files on disk, this byte contains the MSB of the block number 
to begin the read. This byte is combined with the word at XRBLK 
to form a 24-bit field defining the block number. This byte is 
ignored for nondisk devices. 


For channels opened as file-structured, this word defines the 
starting block number for this read. (For large files, this word 
forms the LSB of the block number to start the read.) The value 
performs the same action as the BLOCK option for disk and 

the RECORD option for flexible diskette and non-file-structured 
DECtape (see the RSTS/E Programming Manual). Note that this 
word is ignored if the device is not a random-access device. 


If the device is random-access and this field is nonzero, it is 
interpreted as the block number where the read is to start (1 to n, 
where n is the length of the file, in 512-byte blocks). If the field 
is zero, the next sequential block is read. For example, if a disk 
file is being read with a 1024-byte buffer size, a .READA with this 
parameter equal to four would cause the fourth and fifth blocks of 
the file (512 bytes each) to be read into the buffer. 


For channels opened on disk as non-file-structured MODE 0, this 
word defines the device cluster number where the read is to begin. 
In this case, each .READA begins with a new device cluster, so 
the buffer size at XRB+XRLEN should be a multiple of the device 


cluster size. 


If positive, the maximum time to wait for terminal input data, in 
seconds. Zero indicates an infinite wait. A negative value (bit 15 
equals 1) indicates an infinite keyboard monitor wait. This wait 
is used by run-time systems that act as keyboard monitors for 
their command input. This type of wait time acts as a flag to the 
monitor and to the batch subsystem that the job is in a command 
input wait state. 


Input operation modifier. For disk asynchronous reads, a value of 
one in this byte indicates that a read check should be performed. 
A read check does not transfer any data. The buffer address 
specified in the XRB is compared with the data on the disk. 


Data Returned on Completion of the Directive 


No meaningful data is returned by the directive except for a possible error code in 
byte 0 of the FIRQB. Useful data is returned instead to the completion routine. 


Data Returned to the Completion Routine 


FIRQB 


Mne- Octal Octal Mne- 
monic Offset Olset monic 


0 


a Te 4 


2 FQJOB 
4 


6 FQPPN 


10 


12 


14 


16 


| 20 


| 22 


| 24 


| 26 


30 
32 
34 


36 


XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


XRBLKM7 
11 
13 


15 


XRB+XRBC 


XRB+XRBLKM 


2 XRBC 


10 XRBLK 


12 


14 


Actual number of bytes just read. The value is between zero 
and the value of XRB+XRLEN passed in the XRB. If an error is 
returned on the read (as indicated by byte 0 of the FIRQB), this 
word may or may not be zero. That is, data may be input even if 
an error occurs. 


For disk files, this byte contains the MSB of the block number just 
read. (See XRB+XRBLE.) 
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XRB+XRBLK For random-access devices (see Table 3-5), this word contains the 
block number of the block just input with this .READA. Block 
numbers range from 1 to n (where n is the length of the file, 
in 512-byte blocks); they define the order in which the file was 
written. (For disks opened non-file-structured MODE 0, this is the 
device cluster number.) 


Errors 


There are three classes of errors that can cause the failure of an asynchronous 
I/O request: directive errors; system-driver errors; and device-dependent errors. 


Directive errors are immediately visible upon examination of the FIRQB on 
return from the directive. These errors are similar to the syntax errors checked 
by a compiler. If an error is found, the I/O is not attempted, and the error is 
reported through the standard FIRQB+0 mechanism. Some common directive 
errors are: 


BADCNT The completion routine address is invalid or odd. 
BSERR The specified channel number is illegal. 
NOTOPN No file or device is open on the specified channel number. 


PRVIOL The file or device open on the specified channel is write-only, or the caller 
did not obtain read access to the file or device when it was opened. 


System-driver errors occur before the asynchronous request is issued to the ap- 
propriate device driver. These errors are related to the lack of system resources, 
for example: 


INUSE Too much outstanding I/O for the job, or the job does not have the TUNE 
privilege and already has outstanding asynchronous I/O. 


NOBUFS The system could not get a small buffer for the request. 


Any of the previous errors are reported on return from the .READA directive. 

If none of these errors occurred, the read operation is started and the directive 
returns a value of 0 in FIRQB+0. The read operation may still fail at a later 
point; its success or failure is indicated in FIRQB+0 when the completion routine 
is entered. 


Other system-driver errors are reported within the AST completion routine: 


EOF Eind-of-file (EOF) on the specified device. 
NOROOM No room for the user on the specified device. 


Device-dependent errors can only be found during the attempt of the actual I/O 
transfer. These errors can only be reported to the job in the asynchronous I/O 
completion routine. Some common device-dependent errors are: 


DATERR Some data error occurred. There may or may not be any valid data in the 
input buffer. This error is issued for parity errors, bad card columns, and so 
on. 

HNGDEV Some hard device I/O error occurred. There is usually no data in the input 
buffer when this error occurs. (For example, a .READA for an off-line device 
causes this error.) 


Example 


The following is an example of an asynchronous disk-to-disk copy. The program 
initially issues three read requests (.READA, which requires the TUNE privilege 
for multiple read operations) on the first disk and issues a corresponding write 
request (.WRITA) on the second device when each .READA completes. After each 
-WRITA completes, another advanced .READA is issued. Thus, there is always 
one outstanding .READA and at least one outstanding .WRITA. Each new I/O 


request within the routine uses the same buffer address as the request that has 
just finished. This is an easy way to keep track of the free buffers. 


Note that the program does not handle bad blocks efficiently; nor does it prompt 
for the disk specifications. All errors are treated as fatal. | 


; Register usage: 
; R2 = Input block number 


R4 = 
-PSECT 


START: 


; Open 


se 8s "9 


=e eo "es 


10S: 


20S: 


;All .READA’s come here at completion time 


? 


RSAST: 


CODE 
CALL 


input disk 


MOVB 
MOVB 
MOV 
MOV 
MOV 
CALFIP 
MOV 
BNE 


Open output disk device = 


MOVB 
MOVB 
MOV 
MOV 
CALFIP 
MOV 
BNE 


Issue the first 


CALL 
MOV 
CLR 
MOV 


MOV 
CLR 
MOV 
MOVB 
INC 
MOV 
MOV 
MOV 
» READA 
MOV 
BNE 
ADD 
SOB 


MOV 
» SLEEP 
BR 


MOV 
BRO 
CMPB 
BEQ 
BR 


CLRFOB 


device = DLO: 

#OPNFQ, FIROB+FOFUN 
#3*2,FIRQB+FOFIL 

#"DL, FIRQB+FQDEV 
#377*400+0, FIRQB+FODEVN 


#200*400+8192.,FIRQB+FQMODE ; 


FIRQB, RO 
FATAL 


DL1: 
#OPNFQ, FIROB+FQFUN 


#4*2,F IRQB+FQOFIL 
#"DL, FIRQB+FQDEV 


#377* 40041, FIRQB+FQDEVN 


FIROQB, RO 
FATAL 


three initial reads 


CLRFQX 
#3,R1 

R2 
#BUFFER, R4 


#512.,XRB+XRLEN 
XRB+XRBC 

R4, XRB+XRLOC 
#3*2,XRB+XRCI 

R2 

R2, XRB+XRBLK 
#RSAST, FIRQB+FQFIL 
R4, FIRQB+FQPPN 


FIROB, RO 
FATAL 
#512.,R4 
R1,10$ 


#100001, XRB+0 


208 


FIRQB, RO 
60S 

#13, RO 
CLSIN 
FATAL 


a 
f 
e 
oA 


® 
if 


Buffer number (carried in the user-created parameter field) 


Clear FIRQOB 


Function code 
Set input channel = 3 
on an RLO2 


unit 0, device real 
read-only mode 
Go for it 
Error? 


Stop and check it out 


Function code 
Set output channel = 4 
on an RLO2 
unit 1, device real 
Go for it 
Error? 
Stop and check it out 


Clear FIROB & XRB 
1 read + 2 read-aheads 


Start at virtual block zero 


Load lst buffer address 


Set buffer size to 512. 
XRBC = O 


Set our next buffer address 


Input channel times 2 
Next input block number 
Read that block 

Go to RSAST after read 
User-created parameter 
Do an asynchronous read 
Directive error? 

Yes, stop 

Get next buffer address 
Issue next read-ahead 


Conditional sleep 


and do that until done 


Error’ 

No, continue 
End-of-disk (EOD) ? 
Yes, close I/O disks 


No, unexpected error, stop 


-READA 3-175 


3-176 .READA 


60S: 


All .WRITA’s come here at completion time 


WSAST: 


70S: 


AST common code 


; 
ASTDON: 


; 
- SBTTL 
- ENABL 


CLRFOX: 
CLRFQB: 


CLRXRB: 


MOV 
MOV 
MOV 
MOVB 


MOV 
~-WRITA 
BR 


MOV 
BEQ 
CMPB 
BEQ 
BR 


MOV 
CLR 
MOV 
MOVB 
INC 
MOV 
MOV 

- READA 
BR 


MOV 
BNE 
~-ASTX 


#512., XRB+XRLEN 
#512.,XRB+XRBC 
FIRQB+FQPPN, XRB+XRLOC 
#4*2,XRB+XRCI 


#WSAST, FIRQB+FOFIL 


-ASTDON 


FIRQB, RO 
70$ 

#13, RO 
CLSIN 
FATAL 


#512.,XRB+XRLEN 
XRB+XRBC 

FIRQB+FOPPN, XRB+XRLOC 
#3%*2,XRB+XRCI 

R2 

R2, XRB+XRBLK 

#RSAST, FIROB+FOFIL 


ASTDON 


FIRQB, RO 
FATAL 


FIRQB/XRB clearing routines 


LSB 


PUSH 
MOV 
MOV 
BR 


PUSH 
MOV 
MOV 
BR 


PUSH 
MOV 
MOV 


<RO, R1> 
#F TROB, RO 


#<<FQBSIZ+XRBSIZ>/2>,R1 


2008 


<RO, R1> 
#F IROB, RO 


Re we Ws “ee We =o 


“e “=a “oe 


“e “5 


Reset buffer size 

Want to write entire buffer 
Use the same buffer address 
Output channel * 2 

XRBLK has block number 
Completion routine address 
Write that block 

Join the common code 


Error? 

No, continue 
End-of-disk (EOF) ? 
Yes, close I/O disks 


No, unexpected error, stop 


Set buffer size 

XRBC = zero 

Use the same buffer address 
Input channel * 2 

Increment to next block 
XRBLK has block number 
Completion routine address 
Read that block 

Join the common code 


Any directive errors 
Yes, stop 
No, just return to mainline 


Save RO, Rl 
Point to FIRQB 
Compute how many words 


Save RO, Rl 
Point to FIRQB 


#<FOQBSIZ/2>,R1; Compute how many words 


2008S 


<RO, R1> 
#XRB, RO 


’ 


* 
a 


Save RO, Rl 
Point to XRB 


#<XRBSIZ/2>,R1; Compute how many words 


2008S: CLR (RO) + > Zero it out 


SOB R1,200$ ; Until all done 
POP <R1,RO> ; Restore RO, R1 
RETURN 


> Errors (code in RO) come here 


FATAL: BPT ; All errors come here 

OUT: -EXIT ; All done 

: Close input disk (may still have outstanding .READAs) 

CLSIN: CALL CLRFEFQB >; Clear FIRQB 
MOVB #CLSFQ, FIRQB+FQFUN ; CLOSE function 
MOVB #3*2,F IROBt+FOFIL > Set channel = 3 
CALFIP & Do Le 

; Close output disk (may still have outstanding .WRITAs) 

CLSIN: CALL CLRFQB ; Clear FIRQB 
MOVB #CLSFQ, FIRQB+FQFUN : CLOSE function 
MOVB #4*2,F IRQOBt+FOFIL ; Set channel = 4 
CALFIP DO: Ac 
BR OUT ; Then, exit 


-PSECT DATA 


BUFFER: - BLKB Bilis > Buffer one 

- BLKB 512. s Buffer two 

- BLKB BZ. : Buffer three 
BUFEND: : Address for EOB 
- END START 


-READA 3-177 


3.23  .RTS — Pass Control to Run-Time System 


3-178 .RTS 


Form 
RTS 


Function 


The .RTS directive passes control to a run-time system at the PNEW entry point, 
where the intent is not to run an executable file (see Chapter 2). .RTS performs 
one of four functions: 


e Passes control to the job’s keyboard monitor 
e¢ Passes control to a named run-time system 


¢ Passes control to a named run-time system and establishes it as the job’s 
keyboard monitor 


e Passes control to a named run-time system without changing job context 
information. 


The first function is generally part of a run-time system’s exit processing; you do 
not normally use .RTS for this purpose in a user program. The following code 
shows how .RTS is used in exit processing (for example, in the RT-11 run-time 
system’s .EXIT directive): 


EXIT s CALL CLRFQOB ; Clear FIRQB 
-RTS ; Exit to default KBM 
JMP PROMPT ; If that’s this KBM, then 


prompt for another command 


The other three functions of .RTS apply to both user programs and run-time 
systems. 


Note that once established, a job’s keyboard monitor replaces the default keyboard 
monitor as the one to which control passes by default. This concept is best 
explained by example. 


The SET JOB/KEYBOARD_MONITOR command uses the .RTS directive to 
establish the run-time system to which it passes control as the job’s keyboard 
monitor (see the RSTS/E System Manager’s Guide). Consider the following 
sequence: 


S SET JOB/KEYBOARD MONITOR=RT11 
-MAC 

MAC>CTRL/C 

-CTRL/C 

-SSET JOB/KEYBOARD MONITOR 


$ 


The first line shows the DCL prompt ($), indicating that the user is in the DCL 
keyboard monitor. Then: 


1. The user executes the SET JOB/KEYBOARD_MONITOR command to pass 
control to the RT-11 run-time system. This command establishes RT-11 as 
the job’s keyboard monitor. The RT-11 run-time system displays the period 
prompt. 


2. The user runs MAC, the RSX assembler. Control passes to the RSX emulator, 
which loads the assembler and runs it. MAC displays the "MAC>" prompt. 


3. The user, realizing the mistake in typing MAC instead of MACRO, enters 
Ctrl/C to exit. Since RT-11 has been established as the job’s keyboard monitor, 
control passes back to RT-11, and it displays the period prompt. 


4, The user, wanting to get back to DCL, enters another Ctrl/C. Since RT-11 is 


the job’s keyboard monitor, however, another period prompt appears. 


The user finally issues the SET JOB/KEYBOARD_MONITOR command (with 
the $ prefix to indicate that it is a DCL command), leaving out the run-time 
system name. This command transfers control back to the system default 
keyboard monitor (DCL), establishing it once again as the job’s keyboard 
monitor. 


The four cases in which the .RTS directive can be used are: 


In the first case, the .RTS directive is used to switch control back to the 
run-time system already established as the job’s keyboard monitor. In this 
case, the name of the run-time system is not known. The word in the FIRQB 
that would contain the first part of the run-time system name is zero. If the 
run-time system that issues the .RTS is not itself the job’s keyboard monitor, 
or the currently running program is a privileged program, control is passed to 
the job keyboard monitor at entry point PNEW. If the run-time system that 
issues the .RTS is the job’s keyboard monitor and the current program is not 
a privileged program, control returns to the instruction following the .RTS 
with no error indicated. 


In the second case, the .RTS directive is used to switch control to the run- 
time system named in the FIRQB. (Run-time systems are made known to the 
monitor by the system manager with the INSTALL/RUNTIME_SYSTEM com- 
mand. With this command, the system manager defines a file (ilename.RTS) 
as an auxiliary run-time system. The monitor regards "filename’ as the run- 
time system’s name.) If the run-time system that issues the .RTS directive 
is not itself the named run-time system, or the currently running program 

is a privileged program, control passes to the named run-time system at the 
P.NEW entry point. If the run-time system that issues the .RTS directive 

is the named run-time system and the current program is not a privileged 
program, control returns to the instruction following the .RTS with no error 
indication. If the named run-time system does not exist or is not available 
for some reason, control returns to the instruction following the .RTS with an 
error in byte 0 of the FIRQB. 


In the third case, the .RTS directive is used to switch control to a named 
run-time system and establish it as the job’s keyboard monitor. If the run- 
time system that issues the .RTS is not itself the named run-time system, 

or the currently running program is a privileged program, control passes 

to the named run-time system at the P NEW entry point, and the named 
run-time system is established as the job’s keyboard monitor. If the run- 
time system that issues the .RTS names itself as the run-time system and the 
current program is not a privileged program, control returns to the instruction 
following the .RTS with no error, and the run-time system is established as 
the job’s keyboard monitor. If the named run-time system does not exist or 

is unavailable, control returns to the instruction following the .RTS with an 
error in byte 0 of the FIRQB. 


In the fourth case, the .RTS directive is used to switch control to a named 
run-time system preserving the job’s current job-context information. Control 
passes to the named run-time system at the PNEW entry point, but the 
monitor does not refresh the keyword, reset the stack pointer, or perform any 
of the initialization operations (see the discussion of P NEW in Chapter 2). 


RTS 3-179 


3-180 .RTS 


In the first three cases, if the program currently running had temporary privi- 
leges in effect at one time (whether it has since dropped them or not), then the 
transfer of control to the PNEW entry point is unconditional. In addition, all of 
the user’s memory above NSTORG is cleared to ensure any restricted data kept 
by the program is erased from memory. Finally, the monitor drops temporary 
privileges. 


NOTE 


Do not use this directive from programs running under the RT-11 
run-time system, because RT-11 uses the lowest 512 bytes differently 
than other run-time systems. The correct way to terminate a program 
running under RT-11 is to exit through the RT-11 emulator. 


Although you can use this directive to terminate a program running 
under the RSX run-time system, Digital recommends that you use the 
RSX EXIT$ or EXST$ directive instead (see Chapter 5). Using .RTS 
may cause unexpected results. 


Privileges Required 


None 


Data Passed 


FIROQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


run-time system name 


10 FQNAM1 


(2 words of RADSO) 12 


[teh Roma aon hangs content 


14 FQEXT 
16 


20 


22 


24 


26 


30 


32 


34 


36 


FIRQB+FQNAM1 If control is being passed to a named run-time system (cases 2, 3, 
and 4 described previously), the name of the run-time system is 
stored as two words in RAD50 format beginning here. If control 
is being passed to the job’s keyboard monitor (case 1), the word 
beginning here must contain a value of zero. 


FIRQB+FQEXT To establish a named run-time system as the job’s keyboard 
monitor (case 3), set this word to -1. To switch control to a named 
run-time system without altering job-context information (case 4), 
set this word to —2. When the word at FIRQB+FQNAM1 is zero, 
this word is ignored. 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 LEELA LEIA LILLE LT STITT. | O 
3 PEETTATI LAT AT ATTA TAT ad | 2 
5 4 
7 6 
11 10 XRBLK 
13 unaltered whether or not | 12 
control passes to newrun-time system | 
15 | | 14 
XRB+XRBLK The three words starting at this location pass unaltered to the 
new run-time system. They are also unaltered if control returns 


in line. 


Data Returned 


Since control usually passes to some other run-time system at its PNEW entry 
point, no arguments as such are returned by .RTS. The three words starting at 
XRB+10 remain unaltered if control returns in line. 


Errors 

NORTS No run-time system exists with the specified name. 

PRVIOL The named run-time system does exist but cannot be switched to for some 
reason. (For example, if the switch is made to a named run-time system 
with the intent of establishing it as the job’s keyboard monitor and its 
PEKBM bit in the PFLAG word is not set to 1.) 

Example 


The following example establishes NEWRTS (which the system manager must 
have installed with INSTALL/RUNTIME_SYSTEM/KEYBOARD_MONITOR 
command) as the job’s keyboard monitor: 


MOV # “RNEW, FIRQB+FQNAM1 ; Set run-time system 
MOV #°*RRTS, FIRQB+FQNAMI1 +1 ; Name to "NEWRTS" 

MOV #-1,F IRQB+FQEXT ; Establish as job kbm 
-RTS 


RTS 3-181 


3.24 .RUN — Run a Program 


3-182 .RUN 


Form 
-RUN 


Function 


The .RUN directive searches for a binary (executable) file (defined in the FIRQB), 
opens it on channel 15, and passes control to the PRUN entry point of the run- 
time system associated with the file. The associated run-time system is identified 
in the file’s directory information. This directory information is initially set to 
indicate the run-time system under which the file was created. The system 
manager can change the run-time system associated with the file with the SET 
FILE/RUNTIME_SYSTEM command (see the RSTS/E System Manager’s Guide). 


The run-time system is responsible for loading and executing the file (see the 
P.RUN description in Chapter 2). Control is not returned in line unless an error 
occurs. The monitor drops any temporary privileges in effect under the previously 
running program. 

Privileges Required 


File execute access required; either by protection code or privilege (GREAD or 
WREAD). 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


renin 
[poke nie pes aanior 


file name in RAD50 format 


6 FQPPN 


10 FQNAM1 


(2 words) 


rin | 


14 FQEXT 


30 FQDEV 


32 FQDEVN 


36 FQONENT 


FIRQB+FQPPN The PPN of the file to be opened. The project number is specified 
in the high byte, the programmer number in the low byte. If this 
word is passed as zero, the PPN defaults to the PPN of the job 
that issues the .RUN directive. 


FIRQB+FQNAM1 The file name of the file to be opened; two words in RAD5O format. 


FIRQB+FQEXT The file type for the file to be opened; one word in RAD5O format. 
If you set this word to -1, the monitor will search for the file 
name supplied, substituting the default file type for the currently 
installed set of run-time systems until a file with the given name 
and one of the default file types is found. 


FIRQB+FQDEV The device name of the file to be opened, as two ASCII characters. 
If the device name is not a disk, the .RUN directive returns in line 
with one of the soft errors described in the Errors section. If you 
pass a full word of zero here and in FIRQB+FQDEVN, the public 
disk structure (SY:) is searched for the named file. 


FIRQB+FQNENT A 16-bit parameter word can be passed to the run-time system 
here. If the calling program has temporary privileges in effect, 
bit 15 is unchanged. Otherwise, bit 15 is cleared. The monitor 
takes no other action as a result of the contents of this word; any 
processing is up to the run-time system. (See the PRUN entry 
point, Chapter 2.) 


Errors 


When an error occurs in a .RUN, FIRQB+FQFLAG is set to zero to indicate a 
hard error or -1 to indicate a soft error. 


A hard error means the .RUN failed. A soft error also means the .RUN failed, 
but the run-time system may be able to recover. For example, when you use the 
BASIC-PLUS RUN command, BASIC-PLUS first executes a .RUN. If the RUN 
returns a soft error, BASIC-PLUS performs an OLD (which compiles the program) 
and then executes .RUN again. 


Hard Errors 


BADNAM The specified file name was zero. This is an illegal file name for disk files. 
DEVNES The specified disk device is currently being used non-file-structured. 


NOTCLS Channel 15 is currently open. It must be closed before any .RUN call. (This 
error occurs only if channel 15 is open on a nondisk device. If a disk file is 
open, the channel is closed automatically. ) 


NODEVC The specified device does not exist or is in an illegal format. 


NORTS The run-time system named in the file’s directory information has not been 
installed. 


NOTMNT The specified disk device is not now mounted. 
PAKLCK The disk pack on which the file exists is locked against further file opens. 


Soft Errors 


NOSUCH The file was not found. Note that if FIRQB+FQEXT was -1 in the data 
passed, the monitor has looked for the given file name with all default 
runnable file types for the currently installed run-time systems. In this 
case, a source version of the file may stil] exist. 


PRVIOL The device is not disk but is still a legal device on the system. Or the file 
was found and is on disk but does not have the compiled program bit set in 
its file protection code (bit 6). 


-RUN 3-183 


Example 


The following example uses the .FSS directive to translate a user-typed string 
to the FIRQB format. If no errors in the .FSS occur, a test is made to see if a 
file type was specified. If not, a -1 is supplied in FIRQB+FQEXT so the monitor 
searches for the given file name with all possible default file types that are 
runnable. 


(read user-typed line, set up FIRQB for .FSS) 


-FSS 
TSTB FIRQB ; Error on .FSS? 
BNE ERRTN ; Branch to process error 
BIT #100000, XRB+XRBLK ; Invalid device name? 
BNE BADDEV ; Branch to process error 
BIT #10, XRB+XRBLK ; File type given? 
BNE SKIP1 ; Yes, skip next 
MOV #-1, FIRQB+FQEXT ; No, search all 

SKIP1: CLR FIRQB+FONENT ; Entry parameter is zero 
- RUN 


3-184 .RUN 


3.25 .SET — Set Keyword Bits 


Form 
SET 


Function 


The .SET directive sets certain bits in the keyword (KEY) location in the user job 
image (see Chapter 2). The bits to be set are passed to the monitor in the XRB. 


Privileges Required 


TUNE is required to set the special run priority bit (JFSPRI) or the lock in 
memory bit (JFLOCK). 


Data Passed 


XRB 
Mine- Octal Octal Mne- 
monic Offset Offset monic 


[rien 
[rien 
[rere 
[rire 


O XRLEN 


13 12 


15 14 


JFSPRI JDFSTM 
JFFPP 
JFPRIV 
JFSYS 
JFNOPR 
JFBIG 
JFLOCK 


i6 14 13 12 11 «10 9 8 7 6 5 4 3 2 1 0 


J FLOCK Can be set only by jobs with TUNE privilege. When this bit is set, the 
monitor swaps the user job image out of memory only when: 


e The job issues a .CORE directive to expand the memory allocated for 
the user job image, and there is not. sufficient room in physical memory 
to do the expansion. In this case, the job is swapped out to disk and 
back in at the indicated size. 


e A fatal error, such as a memory parity failure, occurs. 


SET 3-185 


3-186 .SET 


JFBIG 


JFNOPR 
JESYS 


JEFPRIV 
JFEFPP 


JFSPRI 


JDFSTM 


Cannot be set by any job; masked off, that is, the corresponding bits in KEY 
cannot be set by the job with the .SET directive. 


Cannot be set by any job; masked off. 


Can be set by a job only if JFSYS was set at one time and the temporary 
privileges gained were only temporarily dropped. (See description of KEY, 
Chapter 2 and the .CLEAR directive.) 


Cannot be set by any job; masked off. 


Can be set by any caller if the PDP-11/45 compatible hardware floating-point 
unit exists; masked off if it does not exist. When this bit is set, the monitor 
will save information in the floating-point unit as part of the job-context 
information kept when jobs are swapped in and out of memory. 


Can be set only by a caller with TUNE privilege. Setting JFSPRI raises 
the job’s run priority by one-half step. (That is, it sets bit 2 of the system- 
controlled low-order three bits of the run priority. Priorities are normally 
set by the system manager.) 


Can be set by any caller. Enables the fast-mapping facility for the current 
job. If you set this bit, clear all the others. 


All other bits in the XRB word are masked off. 


Data Returned 


The .SET directive does not return any meaningful data. 


Errors 


No errors are possible with the .SET directive. 


Example 


The following code sets JFLOCK, allowing the job to remain locked in memory: 


MOV 
- SET 


#JF LOCK, XRB+XRLEN ;SET JFLOCK 


3.26 .SLEEP — Suspend Job 


Form 
SLEEP 


Function 


The .SLEEP directive causes the monitor to suspend the job for some specified 
time interval or until an event occurs that the job should be aware of. Optionally, 
the monitor checks, before the job is suspended, to see if some event has already 
occurred which would cause it to awaken. If so, the job is not suspended. Control 
returns in line in either case. 


When a .SLEEP is executed, execution of the job is suspended until one of the 
following happens: 


¢ The sleep time (specified in the XRB) expires. 


e A local or network message is queued for the job assuming that the job is 
using local or network send/receive services. (See the .MESAG directive.) 


e¢ A delimiter is typed on a terminal that this job has opened or assigned. 


e The system manager disables logins. (This could occur if the system is being 
shut down.) 


e A state change occurs on a pseudo keyboard assigned to the job. (The job has 
printed output for the controlling job to read or has entered an input wait 
state.) 


e The DMC11/DMR11 driver (XM:) is open and a message is pending for the 
job. 


e An AST completion is queued. 

e¢ The system time is changed. 

If you request it, the monitor checks for the following conditions before suspend- 
ing the job: 


e A delimiter has been typed on any terminal opened by the job or any terminal 
assigned to the job if the job also has a keyboard open on a nonzero channel. 


e A message has been queued for the job. 
e A state change has occurred on a pseudo keyboard opened by the job. 


e The job has a DMC11/DMR11 device driver open and a message has been 
received by that device driver. 


¢ One or more AST completion routines are pending. 


If the monitor determines that any of these conditions are true, it does not 
execute the SLEEP. This feature is known as conditional sleep. 


SLEEP 3-187 


3-188 .SLEEP 


Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


rnin 


XRB+XRLEN This word defines the sleep interval, in seconds. If the value is 
zero, then .SLEEP returns immediately. If bit 15 is set, the moni- 
tor performs the conditional sleep checks. If any of the previously 
listed conditions are present, the SLEEP is not executed. 


0 XRLEN 


12 


14 


Data Returned 
The .SLEEP directive does not return any meaningful data. 


Errors 


No errors are possible with the .SLEEP directive. 


Example 


MOV #5, XRB+XRLEN ; Set timer to 5 seconds 
. SLEEP 


3.26 .SLEEP — Suspend Job 


Form 
SLEEP 


Function 


The .SLEEP directive causes the monitor to suspend the job for some specified 
time interval or until an event occurs that the job should be aware of. Optionally, 
the monitor checks, before the job is suspended, to see if some event has already 
occurred which would cause it to awaken. If so, the job is not suspended. Control 
returns in line in either case. 


When a .SLEEP is executed, execution of the job is suspended until one of the 
following happens: 


° The sleep time (specified in the XRB) expires. 


e A local or network message is queued for the job assuming that the job is 
using local or network send/receive services. (See the .MESAG directive.) 


e A delimiter is typed on a terminal that this job has opened or assigned. 


¢ The system manager disables logins. (This could occur if the system is being 
shut down.) 


¢ A state change occurs on a pseudo keyboard assigned to the job. (The job has 
printed output for the controlling job to read or has entered an input wait 
state.) 


e The DMC11/DMR11 driver (XM:) is open and a message is pending for the 
job. 


e An AST completion is queued. 

e The system time is changed. 

If you request it, the monitor checks for the following conditions before suspend- 
ing the job: 


e A delimiter has been typed on any terminal opened by the job or any terminal 
assigned to the job if the job also has a keyboard open on a nonzero channel. 


e A message has been queued for the job. 
e A state change has occurred on a pseudo keyboard opened by the job. 


°¢ The job has a DMC11/DMR11 device driver open and a message has been 
received by that device driver. 


e One or more AST completion routines are pending. 


If the monitor determines that any of these conditions are true, it does not 
execute the SLEEP. This feature is known as conditional sleep. 


SLEEP 3-187 


3-188 .SLEEP 


Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[rin 


XRB+XRLEN This word defines the sleep interval, in seconds. If the value is 
zero, then .SLEEP returns immediately. If bit 15 is set, the moni- 
tor performs the conditional sleep checks. If any of the previously 
listed conditions are present, the .SLEEP is not executed. 


0 XRLEN 


12 


14 


Data Returned 


The .SLEEP directive does not return any meaningful data. 


Errors 


No errors are possible with the SLEEP directive. 


Example 


MOV #5, XRB+XRLEN > Set timer to 5 seconds 
- SLEEP 


3.26 .SLEEP — Suspend Job 


Form 
SLEEP 


Function 


The .SLEEP directive causes the monitor to suspend the job for some specified 
time interval or until an event occurs that the job should be aware of. Optionally, 
the monitor checks, before the job is suspended, to see if some event has already 
occurred which would cause it to awaken. If so, the job is not suspended. Control 
returns in line in either case. 


When a .SLEEP is executed, execution of the job is suspended until one of the 
following happens: 


° The sleep time (specified in the XRB) expires. 


e A local or network message is queued for the job assuming that the job is 
using local or network send/receive services. (See the .MESAG directive.) 


e A delimiter is typed on a terminal that this job has opened or assigned. 


¢ The system manager disables logins. (This could occur if the system is being 
shut down.) 


e Astate change occurs on a pseudo keyboard assigned to the job. (The job has 
printed output for the controlling job to read or has entered an input wait 
state.) 


¢ The DMC11/DMR11 driver (XM:) is open and a message is pending for the 
job. 


e An AST completion is queued. 

e The system time is changed. 

If you request it, the monitor checks for the following conditions before suspend- 
ing the job: 


° A delimiter has been typed on any terminal opened by the job or any terminal 
assigned to the job if the job also has a keyboard open on a nonzero channel. 


e A message has been queued for the job. 
e A state change has occurred on a pseudo keyboard opened by the job. 


° The job has a DMC11/DMR11 device driver open and a message has been 
received by that device driver. 


¢ One or more AST completion routines are pending. 


If the monitor determines that any of these conditions are true, it does not 
execute the .SLEEP. This feature is known as conditional sleep. 
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Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


O XRLEN 


rin 


XRB+XRLEN This word defines the sleep interval, in seconds. If the value is 
zero, then .SLEEP returns immediately. If bit 15 is set, the moni- 
tor performs the conditional sleep checks. If any of the previously 
listed conditions are present, the .SLEEP is not executed. 


12 


14 


Data Returned 


The .SLEEP directive does not return any meaningful data. 
Errors 
No errors are possible with the SLEEP directive. 


Example 


MOV #5, XRB+XRLEN ; Set timer to 5 seconds 
. SLEEP 


3.27 .SPEC—Special Functions for I/O 


Form 


(set XRB for special function) 


- SPEC 


Function 


The .SPEC directive performs special functions for: 


Disks 

Flexible diskettes 
Line printers 
Magnetic tapes 
Pseudo keyboards 
Terminals 


Ethernet devices 
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3.2/.1 .SPEC for Disk 


For disk, the .SPEC directive lets you explicitly lock up to seven disk blocks on 

a file open for update (mode parameter). A locked block cannot be accessed by 
another user (or from another channel). This extends the implicit lock feature, by 
which the last block or blocks read on a file open for update cannot be accessed by 
anyone else. The disk special functions also let you release explicit and implicit 
locks. (All locks, both explicit and implicit, are released when the file is closed.) 


There are also two other .SPEC options: 


¢ Perform a comparison operation between the contents of a buffer and one or 
more blocks of a disk file. 


e Truncate a file on an open channel. 


Privileges Required 


None 


Data Passed (Disk—Except Compare and Truncate) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
3 LSB of block number (release) 2 XRBC 
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XRB+XRLEN Defines function to be performed: 
Code Meaning 


mm!) Release any implicit lock and all explicit locks. The 
monitor deallocates the extended internal table space 
it needed to do the explicit locks. (See code 3.) 


Release implicit lock. 
Make implicit lock into explicit lock. 


Release the explicit lock on the block specified by 
the word at XRB+XRBC (LSB) and the byte at 
XRB+XRLOC (MSB). If all three bytes are zero, all 
explicit locks are released, but the monitor does not 
deallocate the extra space needed to do explicit locks. 
(This is useful if you intend to use the explicit lock 
feature again during this run. An error occurs if no 
space is available for this purpose.) 


4 Make implicit lock into explicit lock and release the 
implicit lock. 
5 Truncate the file on channel * 2 (XRB+XRCI) at the 
block number given in XRB+XRBC and XRB+XRLOC. 
XRB+XRBC Both these bytes specify the starting block number for releasing 
XRB+XRLOC an explicit lock. If these bytes are zero, all explicit locks are 


released, but the monitor retains the extended table area it needs 
to maintain these locks. (This is useful if you want to use this 
capability again during a run.) 


XRB+XRCI Channel number times two; defines the channel for the lock/unlock 
operation. 
XRB+XRBLKM Handler index for disk: DSKHND (octal value = 0). 


Data Passed (Disk—Compare) 


XRB 

Mne- Octal Octal Mne- 

monic Offset Offset monic 
XRB+XRBC Size of the data buffer to be compared. 
XRB+XRLOC Address of the data buffer to be compared. 
XRB+XRBLK LSB of the first block number on the disk to be compared with the 

data buffer. 

XRB+XRMOD MSB of the first block number on the disk to be compared with 


the data buffer. 
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Data Passed (Disk—Truncate) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
3 LITA LII IIIT TTI TTT 2 XRBC 
5 LILITIAITITI ITT TTT TT 4 XRLOC 
XRBLKM 7 DSKHND (=0) channel number * 2 6 XRCl 
11 LSB of block number to become last block 10 XRBLK 
13 LALIT TIA T TT 12 
15 l// IIIT MSB of block number 14 ®RMOD 
XRB+XRBLK LSB of the block number on the disk to become the last block of 
the file. 
XRB+XRMOD MSB of the block number on the disk to become the last block of 
| the file. 


Data Returned 


Except for a possible error code in byte 0 of the FIRQB, the disk subfunctions of 
“SPEC do not return any meaningful data. 


Errors 
For subfunction code 1: 


DATERR The data in the buffer does not match the data on the disk. 
For subfunction code 2: 


INTLCK Occurs if the implicit lock overlaps any current explicit lock. For example, if 
you read blocks 1 and 2 into a 1024-byte buffer in update mode, an implicit 
lock exists on blocks 1 and 2. If you explicitly locked these blocks, and then 
read blocks 2 and 3 and tried to explicitly lock blocks 2 and 3, you would get 
this error. An exact match is legal (for example, if the second read also read 
blocks 1 and 2) and results in a no operation. 


NOBUEFS Occurs if the monitor needs to expand its internal table space but memory 
is not available. 


NOROOM There are already seven explicit locks on this channel. 
PRVIOL There is no current implicit lock; that is, no blocks have been read. 


For subfunction code 3: 


NOSUCH The block number specified does not correspond to the first block number of 
| an explicit lock. 
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3.27.2 .SPEC for Ethernet Interface 


The following functions allow the user to manipulate and monitor the Ethernet 


interface. 


3.27.2.1 Set New Physical Address 


The Set New Physical Address .SPEC function changes the physical address of 


the Ethernet controller. 
The following figure illustrates the Physical Address Buffer: 


NOTE 


This call succeeds only if the portal requesting the physical address 
change is the only portal currently open on the controller. The Set 
Physical Address .SPEC function requires SWCTL privilege. 


Data Passed 


XRB 

Mne- Octal Octal Mne- 

monic Offset Offset monic 
XRB+XRLEN Special function code -4; defines function to be performed. 
XRB+XRBC Must be 6, denoting a 6-byte physical address. 
XRB+XRLOC Starting address of the Physical Address Buffer. 
XRB+XRCI Channel number times two; defines the channel. 
XRB+XRBLKM Device handler index: ETHHND. 
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The following errors may occur on a Set Physical Address call: 


Errors 


BADCNT XRBC not equal to six, can’t be a valid physical address. 
BADNAM Invalid physical address (Least Significant Bit must be 0). 
HNGDEV Controller is disabled or inoperative. 

INUSE Other portals are currently open on the controller. 
PRVIOL You do not have appropriate privilege (SWCTL). 


3.2/.2.2 Enable Multicast Addresses 


Use the Enable Multicast Addresses function to let the portal and controller 
receive multicast messages. The XRB contains pointers identifying the User 
Multicast Address Buffer. RSTS/E allows a maximum of five multicast addresses 
per portal on an Ethernet channel. 


The following figure illustrates the User Multicast Buffer: 


User Multicast Address 1 


User Multicast Address 2 


User Multicast Address N 
(N is an integer < = 5) 


(N * 6-2) 


The addresses are loaded into the user buffer with the least significant byte 
loaded in Byte 0 of the address block and the most significant byte loaded in Byte 
5 of the address block. 


Each portal can have a maximum of five six-byte multicast addresses. Each time 
the Enable Multicast Address call is issued, the new addresses supersede the old 
list. 


You can specify a null list (by issuing the call with XRBC = 0) that will supersede 
the old list, thus disabling all multicast reception for that portal. 
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Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 fepeéial function code 0 XRLEN 
3 nee of multicasts * 6 bytes 2 XRBC 
5 starting address 4 XRLOC 
xnatkwr | ETHHND ( oa 50) _ 
11 TALALEIT TILT LETT Fa Pd 10 
13 VEL AA LIAL EAL AAT TATE 12 
15 | CLEP LL LV ACTALLTA ELT fa | 14 
XRB+XRLEN Special function code -3; defines function to be performed. 
XRB+XRBC Number of multicasts times 6 (byte count of buffer). Maximum 
size is 30 bytes. You can issue a byte size of zero to remove all 
enabled multicasts from the portals list without replacing them 
with new ones. 
XRB+XRLOC Starting address of Multicast Buffer. 
XRB+XRCI Channel number times two; defines the channel. 
XRB+XRBLKM Device handler index: ETHHND. 


The following errors may occur on an Enable Multicast Address call: 


Errors 


BADCNT Attempt to add too many multicast addresses, or buffer size input was not a 
multiple of six bytes, indicating an incomplete address. 


BADNAM At least one address is not a valid multicast address, that is, the least 
significant bit of the address is not equal to one. 


HNGDEV The controller is disabled or inoperative. 


3.27.2.3 Get Circuit Counters 


Use the Get Counters function to bring the counters up to date. The controllers 
maintain counters in several places. You must tell the data link layer when you 
want to collect them. The controllers update line or circuit counters only when 
you issue the call. This call does not require privileges. 
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Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. . 
: , 
XRB+XRLEN Special function code 0; defines function to be performed. 
XRB+XRCI Channel number times two; defines the channel. 
XRB+XRBLKM Device handler index: ETHHND. 


All other fields are reserved. The XRB is not modified on return. 


The following errors may occur on a Get Circuit Counters call: 


Errors 


HNGDEV The controller is disabled or inoperative. 


3.27.2.4 Get Line Counters 


Use the Get Line Counters function before a Transfer Line Counters function to 
instruct the data link layer to update the appropriate counters. This call does 
not require privileges. Wait a couple of seconds before issuing the Transfer Line 
Counters call. 


Data Passed 


XRB 
Mine- Octal Octal Mne- 
monic Offset Offset monic 
7 7 
, , 
XRB+XRLEN Special function code -1; defines function to be performed. 
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XRB+XRCI Channel number times two; defines the channel. 
XRB+XRBLKM Device handler index: ETHHND. 


All other fields are reserved. The XRB is not modified on return. 


The following errors may occur on a Get Line Counters call: 
Errors 


HNGDEV The controller is disabled or inoperative. 
en asec gE an a le 
3.27.2.5 Transfer Circuit Counters 


Use the Transfer Counter function to read the counter information from the data 
link layer to the user space once you have updated the information with the Get 
Counters function. 


Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
XRB+XRLEN Special function code 1; defines function to be performed. 
XRB+XRBC Length (in bytes) of transfer. There are up to 32 (octal) bytes of 


counters to return. RSTS/E returns fewer counters if requested, 
but will not transfer an odd number of bytes. 


XRB+XRLOC Start address of user buffer to receive transfer counters. It must 
start on a word boundary. 

XRB+XRCI Channel number times two; defines the channel. 

XRB+XRBLKM Device handler index: ETHHND. 

XRB+XRBLK If XRBLK is zero, it means you only wish to read counters. If 


XRBLEK is nonzero, it means the circuit counters will be cleared 
after they are transferred, if: 


¢ You have SWCTL privilege 


e All circuit counters are read. A partial read of counters 
succeeds, but the counters are not reset after the read. 


All other fields are reserved. 
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Data Returned 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


XRB+XRBC Cleared. All other fields are reserved and contents are not guar- 
anteed. 


Buffer Contents on Return 


current date/time 0 
2 
date/time last 4 
zeroed 6 
10 
bytes received 
12 
14 
bytes sent 
16 
20 
packets received 
22 
24 
packets sent 
(LSB) 26 
user buffer unavailable 30 
0-2 Current date/time stored in standard RSTS/E format. 
4-6 Date/time of last zeroing returned in standard RSTS/E format. 


10-12 Bytes received, stored as an unsigned 32-bit number. 
14-16 Bytes sent, stored as an unsigned 32-bit number. 


20—22 Packets received, stored as an unsigned 32-bit number. The number of mes- 
sages received for this portal, regardless of length. 
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24—26 Packets sent, stored as an unsigned 32-bit number. The number of packets sent 
by this portal. 


30 User buffer unavailable. The number of times that messages received for this 
portal had to be discarded because all of its allocated system receive buffers 
contained pending messages. This is kept as a single 16-bit word. 


Any counters exceeding their maximum value stay at that maximum value 
(65,535 for a single word, 4,294,967,295 for a long word). 


The following errors may occur on a Get Line Counters call: 


Errors 


BADCNT 


HNGDEV 
MAGRLE 


PRVIOL 


Returned if: 


— The user buffer did not start on a word boundary 
— The requested transfer size is not for all counters and is for an odd 


number of bytes. 
The controller is disabled or inoperative. 


A record length error is returned if the transfer requests less than the actual 
number of counters available. However, as many counters as requested are 
transferred into the user buffer. If a clear after transfer was requested, it 
was not done. 


If a transfer and clear operation was attempted and the user doesn’t have 
SWCTL privileges, this error is returned and no operation is performed. 


3.27.2.6 Transfer Line Counters 


Use the Transfer Line Counters function to read the counter information from the 
data link layer to the user space. Issue this call a short time after issuing the Get 
Line Counters function. 


Data Passed 


Mne- Octal 


monic Offset 


XRBLKM7 


11 
13 


15 


XRB+XRLEN 
XRB+XRBC 


XRB+XRLOC 


XRB 
Octal Mne- 
Offset monic 


Special function code -2; defines function to be performed. 


Length (in bytes) of transfer. There are up to 76 (octal) bytes of 
counters to return. RSTS/E returns fewer counters if requested, 
but will not transfer an odd number of bytes. 


Start address of user buffer to receive transfer counters. It must 
start on a word boundary. 
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XRB+XRCI Channel number times two; defines the channel. 
XRB+XRBLKM Device handler index: ETHHND. 


XRB+XRBLK If XRBLK is zero, it means you only wish to read counters. If 
XRBLK is nonzero, it means the circuit counters will be cleared 
after they are transferred, if: 


e You have SWCTL privilege 


e All circuit counters are read. A partial read of counters 
succeeds, but the counters are not reset after the read. 


All other fields are reserved. 


NOTE 


If DECnet/E is operating on the controller, as well as a user portal, 
Digital recommends that the line counters only be cleared using the 
NCP Zero Line Counters function. This helps in troubleshooting line 
problems by keeping all the line counters in one place. 


Data Returned 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


— 
[iin 


XRB+XRBC Cleared. All other fields are reserved and contents are not guar- 
anteed. 


2 XRBC 
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Buffer Contents on Return 


current date/time 


date/time last 


zeroed 


bytes received 
bytes sent 
multicast bytes 
packets received 


packets sent 


(MSB) 
multicast packets received 
(LSB) 
packets sent, 
initially deferred 


packets sent, 


single collision 


packets sent, 


50 

multiple collision (LSB) 52 

; 
: 
: 
: 
; 
: 
r 
“eitee buffer unavailable 72 

: 
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0-2 
4—6 
10-12 
14-16 
20-22 


24—26 
30-32 


34—36 


40-42 


44-46 


50-52 


54 


56 


60 
62 
64 


66 


710 
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Current date/time stored in standard RSTS/E format. 

Date/time of last zeroing returned in standard RSTS/E format. 
Bytes received on channel, stored as an unsigned 32-bit number. 
Bytes sent on channel, stored as an unsigned 32-bit number. 


Multicast bytes received, stored as an unsigned 32-bit number. (Also included 
in the total bytes received, above.) 


Packets received on channel, regardless of length, stored as an unsigned 32-bit 
number. The number of messages received for this portal, regardless of length. 


Packets sent on channel, regardless of length stored as an unsigned 32-bit 
number. The number of packets sent by this portal. 


Multicast packets received on channel, regardless of length, stored as an 


unsigned 32-bit number. (Also included in total number of packets received, 
above.) 


Packets sent but initially deferred, stored as an unsigned 32-bit number. This 
indicates that transmission of a packet was delayed because the Ethernet cable 
was busy when it was first attempted. Subsequent transmission was successful. 


Packets sent with a single collision, stored as an unsigned 32-bit number. This 
indicates that a collision occurred during the first attempted transmission of 
the packet. The second attempt succeeded. 


Packets sent with multiple collisions, stored as an unsigned 32-bit number. 
This indicates that a collision occurred during more than one attempted trans- 
mission of the packet. Eventually, it succeeded. 

Transmit failed count, stored as an unsigned 16-bit number. The number of 


failed transmissions that have occurred on the line. 


Transmit failure flag word. This word contains bits indicating the causes for 
transmission failures: 


e¢ 1—indicates transmission failed because of too many collisions. The data 
link layer typically tries 16 times to put a message on the Ethernet. 


e 2—indicates a loss of carrier on the last transmission attempt. 


e 10—indicates that the attempted transmission length was greater than 
1518 bytes long. This should not occur on RSTS/E systems. 


e 20—indicates that a late collision happened on the last transmission 
attempt. 


Collision detect check failures, stored as an unsigned 16-bit word. 
Receive failure count, stored as an unsigned 16-bit word. 


Receive failure flag word. This word contains bits indicating what types of 
receive failures have occurred since the counters were last cleared: 


e 1—CRC was invalid indicating garbled reception 
e 2—Framing error. Invalid CRC and a partial byte received. 
e 4—Message exceeded Ethernet maximum length of 1518 bytes. 


Unrecognized destination, stored as an unsigned 16-bit word. This is a count 
of the number of times that the controller received messages destined for the 
physical address of this controller, but with unrecognized protocol type field. 
That is, there is no portal open to process messages of this type but someone is 
still sending them. 


Data overrun, stored as an unsigned 16-bit word. 


72 


74 


System buffer unavailable, stored as an unsigned 16-bit word. This contains 
a count of the number of times the controller had to throw away received 
messages because there were no buffers available at the time. 


User buffer unavailable, stored as an unsigned 16-bit word. The number of 
times that messages received for this portal had to be discarded because all of 
its allocated receive buffers contained pending messages. 


If any counters exceed their maximum value, they stay at that maximum value 
(65,535 for a single word, 4,294,967,295 for a long word). 


The following errors may occur on a Get Line Counters call: 


Errors 


BADCNT 


DATERR 


HNGDEV 
MAGRLE 


PRVIOL 


Returned if: 


— The user buffer did not start on a word boundary 


— The buffer size in XRBC is less that the total line counters and is for an 
odd number of bytes. 


The data link layer has not yet finished processing the Get Line Counters 
function. Try again in a few seconds. 


The controller is disabled or inoperative. 


A record length error is returned if the transfer requests less than the actual 
number of counters available. However, as many counter as requested are 
transferred into the user buffer. If a clear after transfer was requested, it 
was not done. 


If a transfer and clear operation was attempted and the user doesn’t have 
SWCTL privileges, this error is returned. 
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3.27.3 .SPEC for Flexible Diskette 


For RX02 flexible diskette devices, the SPEC directive lets you: 
e Obtain the density (single or double) of the current flexible diskette 
e Mount a new flexible diskette and recompute the density 


e Reformat an RX02 flexible diskette for a desired density 


Because the RX02 flexible diskette drive supports single and double density 
flexible diskettes, the SPEC function is especially useful for programmed flexible 
diskette operations. For example, .SPEC allows you to mount a series of single 
and double density flexible diskettes without having to close and reopen the 
device for each mount. Normally, the driver computes density once: during the 
initial open. If you insert a second flexible diskette that is incompatible with the 
initially computed density, a read or write operation fails. SPEC lets you include 
an instruction in your program that causes the driver to recompute the density. 
In addition, for RX02 flexible diskette drives, .SPEC permits you to specify a 
density reformat operation. 


SPEC can require as much as 20 seconds to reformat the density of the RX02 
flexible diskette and cannot be interrupted with Ctrl/C. Note that if the operation 
is interrupted (by power failure or catastrophic error), the flexible diskette is 
rendered unusable. That is, the flexible diskette contains both single and double 
density. To recover, you must reformat the flexible diskette. 


Privileges Required 
None 


Data Passed (Flexible Diskette) 


XRB 
Mne- Octal Octal Mnhne- 
monic Offset Offset monic 
s[___ mn _| 
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XRB+XRLEN 


Code Meaning 


Function code specifying the desired operation: 


0 Returns density of currently mounted flexible diskette. 
(The parameter word at XRB+XRBC must be zero.) 


1 Recomputes density and returns density. (The parameter 
word at XRB+XRBC must also be zero.) This code must 
be issued prior to any I/O operation on the flexible 


diskette. 


2 Reformats the current flexible diskette to the density 
specified in the parameter word at XRB+XRBC. Allowed 


only on RX02 drives. 


XRB+XRBC Must equal zero when the function code equals zero or one. 
Otherwise, the parameter word can be: 
Value Meaning 
1 Reformats as single-density (one sector equals 128 bytes) 
2 Reformats as double-density (one sector equals 256 
bytes) 
XRB+XRCI Channel number times two; defines the channel on which the 
flexible diskette is currently open. 
XRB+XRBLKM Handler index for flexible diskette: RXDHND (octal value equals 
22). 
Data Returned 
XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | PET EEEELAT ELLE EEE LA 0 
e[ arnt] aeraty | 2 xR 
5 | ETERS 4 
7 WPATID ATALANTA TS TAA A TAT ES 6 
11 |} LLPATALELA LEELA P IAL Ed 10 
13 IP AAEA ELA L AL ELLE EL OSG. 12 
15 PLTAAT TTA PTS TD EL ETT 14 


XRB+XRBC Density; only returned when the data passed in XRB+XRLEN is 
one or zero. The possible values are: 
1 Single-density (sector equals 128 bytes) 
2 Double-density (sector equals 256 bytes) 

Errors 

ERRERR You tried to reformat on an RXO1 flexible diskette drive. You can use .SPEC 

to reformat flexible diskette density only on RX0O2 drives. 
HNGDEV A hardware error occurred. This can often be a transient condition. Retry 


the operation. 
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3.2/.4 .SPEC for Line Printer 


Privileges Required 


None 


Data Passed (Line Counter Subfunction) 


XRB 
Mne- Octal Octal 
monic Offset Offset 


[serine 
i CTC 


XRBLKM 7 


11 


13 


15 


Mne- 
monic 


XRLEN 
XRBC 
XRLOC 
XRCI 


XRBLK 


XRB+XRLEN The special line printer function to be performed. 


XRB+XRCI Channel number times two; defines the channel on which the line 


printer is currently open. 


XRB+XRBLKM Handler index for line printer: LPAHND (octal value equals 6). 


Data Returned (Line Counter Subfunction) 


XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


XRB+XRBC The value of the 32-bit line counter. The LSB are returned in 


2 XRBC 


XRB+XRBC and the MSB are in XRB+XRBC+2. The counter is 


reset to zero when the line printer is opened. 
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Data Passed (Line Position Subfunction) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
XRB+XRLEN The special line printer function to be performed. 
XRB+XRCI Channel number times two; defines the channel on which the line 
printer is currently open. 
XRB+XRBLKM Handler index for line printer: LPAHND (octal value equals 6). 
Data Returned (Line Position Subfunction) 
XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, . 
| . 
XRB+XRBC The current vertical line position. The value is in the range 0 (top 
of page) to L-1, where L is the page length. 
XRB+XRBC+1 The current horizontal line position. The value is in the range 0 


(left margin) to W-1, where W is the page width. 
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Errors (Line Printer) 


BSERR 
NOTOPN 
PRVIOL 
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An illegal channel number is specified at XRB+XRCI. 
The channel specified at XRB+XRCI is not open. 


Privilege violation; one of the following conditions has occurred: 


e The calling job does not own the specified printer and does not have 
DEVICE privilege. 
e The function code is not 0 or 1. 


e The device open on the channel specified at XRB+XRCI is not a line 
printer. 


3.27.5 .SPEC for Magnetic Tape 


On MT, MM, and MU tape drives, to set the drive density (function code = 13), 
you must mount a tape and position it at the beginning-of-tape (BOT) mark. You 
do not need to mount a tape to check legal densities of a drive or to return the 
current density. 


NOTE 


Any density changes you make with this call remain in effect until 
either a new density is set, or you read a magnetic tape that has a 
density different than the one formerly set. This action is equivalent to 
the STAY value 8192% in the Set Density and Parity function (function 
code = 6). 


Privileges Required 
None 
Data Passed (Magnetic Tape) 
XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


special function code 


1 | 0 XRLEN 
smi | 
XRBLKM 7 | MTAHND (=octal 16) 6 XRCI 
13 | PEAIPRLAASG ELAS LATE T LPL 12 


XRB+XRLEN The special magnetic tape function to be performed (see 
Table 3-6). For a detailed discussion of these functions, see 
the discussion of the MAGTAPE function in the RSTS/E 


Programming Manual. 


XRB+XRBC The meaning of this word varies according to the special function 
code specified at XRB+XRLEN. Table 3-6 summarizes these 
values; for a detailed discussion, see the MAGTAPE function 
description in the RST'S/E Programming Manual. 


XRB+XRCI Channel number times two; defines the channel on which the tape 
is currently open. 

XRB+XRBLKM Handler index for magnetic tape: MTAHND (octal value equals 
16). 
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Table 3-6: Special Functions for Magnetic Tape 


Code Action Parameter Value Returned 
0 Rewind and off-line Unused 0 
1 Write end-of-file Unused 0 
2 Rewind Unused 0 
3 Skip record # records to skip # records not skipped 
4 Backspace over # records to # records not backspaced 
record backspace 
5 Set density and D+P+S 0 
parity 
Tape status function Unused (see Table 3-7) 
7 File characteristics Unused (see Table 3-7) 
10 Rewind on close Unused 0 
11 End of volume Unused 
12 Error condition Unused 
acknowledged 
13 Extended set density 2 (see Table 3-7) 
D= Density 
14 = 800. bpi 
400 = 1600. bpi, phase-encoded 
P= Parity (0 = odd, 1 = even) 3 (800. bpi only) 
S= Stay 


0 = MODE value specified in OPEN does not stay on CLOSE 
20000 = MODE value specified in OPEN is retained after CLOSE 
Current density 
fy If bit 15 is set, the density is set according to the value in Bits 0-14 as follows: 
77777 = highest legal density for the drive 
1 = lowest legal density for the drive 
n = set to n, if legal; otherwise unchanged 
0 If Bit 15 is clear, the density is unchanged but the value passed is tested 


1Parameter word for function code 5: 


2Parameter word for function code 13: 
3Digital recommends that you use odd parity. When you use even parity, you cannot write binary 
data. In addition, many operating systems and tape drives do not support even parity. 
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Daia Returned (Magnetic Tape) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. . 
; 
XRB+XRBC The meaning of this word varies according to the value at 


XRB+XRLEN in the data passed. Table 3-7 summarizes these 
values. For a detailed discussion, see the MAGTAPE function 
description in the RSTS/E Programming Manual. 


Table 3-7: Value Returned by .SPEC for Magnetic Tape 


Bit 


Octal 
Value Meaning 


Value Returned at XRB+XRBC for Function Code 6 (Magnetic Tape Status Word) 


15 
14-13 


12 


11 


a nt DO © 


100000 Last command caused an error. 
If bit 3 = 0, these bits indicate density: 


00000 Reserved 
20000 Reserved 
40000 800. bpi 

60000 Reserved 


If bit 3 = 1, these bits indicate density: 


00000 1600. bpi 
20000 Reserved 
40000 Reserved 
60000 Reserved 


00000 9-track tape 
10000 Reserved 


0000 Odd parity 

4000 Even parity 

2000 Magnetic tape is physically write-locked 

1000 Tape is beyond end-of-tape (HOT) marker 

400 Tape is at beginning-of-tape (BOT) 

200 Last command detected an end-of-file (HOF) 

100 The last command was .READ and the record read was longer than 
the I/O buffer size; that is, part of the record was lost 

40 Unit is nonselectable (off-line) 


(continued on next page) 
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Table 3-7 (Cont.): Value Returned by .SPEC for Magnetic Tape 


Octal 
Bit Value Meaning 


Value Returned at XRB+XRBC for Function Code 6 (Magnetic Tape Status Word) 


4 00 Unit does not accept 1600. bpi 
20 Unit accepts 1600. bpi 


3 00 See values for bits 14-13 
10 See values for bits 14-13 


2-0 Indicates last command issued: 


O = Off-line 


3 = Write EOF 

4 = Rewind 

5 = Skip record 

6 = Backspace record 


Value Returned at XRB+XRBC for Function Code 7 (File Characteristics Word) 
word = 0, DOS format or ANSI U (undefined) format 
word + 0, ANSI format, with bit meanings: 


15-14 40000 F (fixed-length) 
100000 __—iOD (variable-length) 
140000 __sSs (spanned) 


13-12 00000 Carriage control embedded ’M’ 
10000 FORTRAN carriage control ’A 
20000 Implied LF/CR before record ’ ’ 


11-0 --- For Format F, this value is the record length, in bytes. 


For Format D, this value is the maximum record length, in bytes. 


Value Returned at XRB+XRBC for Function Code 13 (File Characteristics Word) 


If value passed was zero, the value returned is the current density 


If value passed was nonzero, the value returned depends on the value passed as follows: 
Bits Passed Returned 


14-0 TT1T7 Highest legal density for the drive 


1 Lowest legal density for the drive 
n Nearest legal density for the drive not greater 
than n 


tANSI format S is not supported by RSTS/E systems. 
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Errors (Function Code = 13) 


BDNERR 


NOTMTA 


The value passed in bits 0-14 of XRB+XRBC is not legal for the specified 
tape drive. The density of the drive is unchanged. 


An attempt was made to set the density of an MT, MM, or MU tape drive for 
which no tape was mounted, or the tape was not at BOT. When you specify 
a density that is not a valid density, the next highest density for the drive 
is returned. If the specified density is higher than the maximum density for 
the drive, the maximum density is returned. 
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3.2/7.6 .SPEC for Pseudo Keyboards 


For pseudo keyboards, the .SPEC function lets you: 


e Disable and enable echo at the controlled job’s keyboard (that is, the KB side 
of the pseudo keyboard). 


e Read a flag word that tells you whether echo is ON or OFF at the controlled 
job’s keyboard. 


e Determine the current exit status of the controlled job. 


A pseudo keyboard receives two kinds of output from a controlled job: character 
echo, which is done by the RSTS/E monitor, and program output, which occurs 
when a program writes to the controlled job’s keyboard. The .SPEC function 
affects only character echo, not program output. 


Character echo is enabled by default. However, in some pseudo keyboard 
applications, it is more convenient to disable character echo. For example, in a 
pseudo keyboard application that uses both a terminal and a pseudo keyboard, 
you get character echo from the terminal. You also get character echo and 
program output from the pseudo keyboard. You can use this function to disable 
character echo at the pseudo keyboard. | 


Privileges Required 


None 


Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
XRB+XRLOC The special function codes; the possible values are: 
Code Meaning 
0 Enable/disable echo or read flag. 
1 Read exit status. 
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XRB+XRBC The action to be performed for the spr. 
Value Meaning 


0 Read the flag word 
255 Enable echo 
—l Disable echo 


XRB+XRCI Channel number times two; defines the channel on which the 
pseudo keyboard is open. 
XRB+XRBLKM Handler index for pseudo keyboard PKHND (octal value = 20). 


Data Returned 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. ) 
: ) 
XRB+XRBC For special function code 0: 
If bit 5 =Q Keyboard echo is enabled. 


= 1 Keyboard echo is disabled. 


For special function code 1, the exit status for the job you are 
controlling. The current exit status value is returned in bits 
0-2 The values have the following meanings: 


QO Warning 

1 Success 

2 Error 

4 Severe error 


Errors 


No errors are possible with the pseudo keyboard subfunction of .SPEC. 
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3.2/.f .SPEC for Terminal 


The .SPEC directive for terminals has two forms. The first form lets you perform 
several different functions, such as cancel Ctrl/O, set modes for tape, echo, and 
ODT, and cancel type-ahead. The second form lets you set, read, and clear private 


delimiters. 


Privileges Required 


SEND to broadcast a message to a terminal. SYSIO to force a command to a 


terminal. 


Data Passed (Terminal—Except Private Delimiters) 


XRB 
Mne- Octal Octal 
monic Offset Offset 
1 [_spesalionction cose id; 
» | Re ror number afte seniose | 
a 


XRB+XRLEN Defines a special function: 
Code Meaning 


Mne- 
monic 


XRLEN 


XRBC 
XRLOC 
XRCI 


XRBLK 


0 Cancel Ctrl/O (see the .TTRST directive) 
1 Set tape mode (see the .TTAPE Set tape mode directive) 
2 Enable echo and clear tape mode (see the .TTECH 


directive) 


Disable echo (see the .TTNCH directive) 
Set ODT mode (see the .TTDDT directive) 


Broadcast to keyboard (SEND privilege required) 


3 
4 
5 Force to keyboard (SYSIO privilege required) 
6 
7 


Cancel all type-ahead 
10 Reserved 
11 Multiple private delimiters 
12 Read Ctrl/C flag 


For XRB+XRLEN = 12, if the caller owns the terminal being 
checked, the Ctrl/C flag is cleared after it is read. Otherwise, the 


flag is just read. 
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XRB+XRBC For XRB+XRLEN = 0, 1, 2, 3, 4, 7, or 12: 


When XRB+XRBC equals 0, these functions take place on the 
terminal currently open for this job. When XRB+XRBC does 


not equal 0, these functions take place on the keyboard number 
specified in XRB+XRBC. This keyboard must be assigned to but 


not opened by the calling job. 
For XRB+XRLEN = 5 or 6: 


XRB+XRBC is the number of bytes to send or force. 


XRB+XRLOC For XRB+XRLEN equal to 5 or 6, this word contains the starting 
address of the bytes to be sent or forced. 

XRB+XRCI Channel number times two; defines the channel for the terminal 
specified at XRB+XRBC. 

XRB+XRBLKM Handler index for terminals; TTYHND (octal value = 2). 

XRB+XRBLK For XRB+XRLEN = 5, 6, or 12, this word contains the keyboard 


number to which the data is to be sent or forced. 


Data Returned (Terminal—Except Private Delimiters) 


XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


[mn | _erace toa 
TTT 


4 


0 XRLEN 


2 XRBC 


XRB+XRLEN A value of zero indicates the Ctrl/C flag was not set. A value of 
377 indicates the Ctrl/C flag was set. This value is only meaning- 


ful when the data passed in XRB+XRLEN was 12. 


XRB+XRBC Number of bytes that could not be sent (returned only when 


XRB+XRLEN in the data passed was six). 


Errors (Terminal—Except Private Delimiter) 


BSERR An illegal channel number is specified at XRB+XRCLI. 


NOTOPN The channel specified at XRB+XRCI is not open. 


PRVIOL Privilege violation; one of the following conditions has occurred: 


¢ The calling job does not own the specified keyboard and does not have 


DEVICE privilege 


e The function code is not 0 to 7 or 11 (returned for all .SPEC calls for 


terminals) 
e An illegal terminal number at XRB+XRBLK 


e The device open on the channel at XRB+XRCI is not a terminal 
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Private Delimiters 


A private delimiter is a character used as a delimiter within a program. You 
can define any printing or nonprinting character to be a private delimiter, for 
example: 


° 6A letter 

e A function key such as DELETE 

e A control character such as Ctrl/Z 

e A standard delimiter such as LINE FEED 

A private delimiter is useful on a data entry terminal with a specialized keyboard. 


You can use a large or conveniently located key as the delimiter key. Private 
delimiters are also useful in keypad applications. 


You can declare one character as a private delimiter or you can declare up to 256 
multiple private delimiters. 


Multiple private delimiters let you do special character processing without using 
single character I/O. For example, by combining escape sequences with private 
delimiters, you can define your own function keys in keypad applications. 


The rest of this section: 
e Provides general information about private delimiters 
e Shows the XRB layouts for setting, reading, and clearing private delimiters 


e Lists all private delimiter masks 


Characteristics of Private Delimiters 


Declaring a character as a private delimiter with the .SPEC directive overrides 
the existing interpretation for the character. Thus, unlike a standard delimiter 
such as RETURN or LINE FEED, a private delimiter does not echo at the 
terminal. In addition, a special character no longer performs its normal function. 
For example, when the DELETE key is a private delimiter, it does not erase the 
last character typed. 


A private delimiter has basically the same characteristics as a standard delimiter. 
Like a standard delimiter, it: 


e Terminates a .READ on the terminal. 


e Cannot be deleted except by Ctrl/X. The DELETE key and Ctrl/U do not affect 
private delimiters in the type-ahead buffer. (Ctrl/X cancels all type-ahead 
buffering.) 


e Causes the system to awaken a sleeping job when typed at a terminal that 
the job has open or assigned. 


Once set, a private delimiter remains in effect for a terminal until one of the 
following occurs: 
e The program clears it 


¢ The job releases the terminal by deassigning it or by closing the I/O channel 
where the terminal is open 


° ©The job terminates 


In addition, the system clears private delimiters when a dial-up line gets hung up 
or the job controlling the terminal is killed. 
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Private delimiters change the way characters are processed in binary mode 
(MODE 1). When a terminal is open in binary mode and no private delimiter is 
in use, the system terminates a read after every character. However, if one or 
more private delimiters are in use, the system terminates a read only when a 
private delimiter is typed. 


The system processes private delimiters after processing Ctrl/S and Ctrl/Q (Gf the 
TTSYNC characteristic is set) and escape sequences (if the terminal is in escape 
sequence mode). This feature prevents a terminal from becoming permanently 
stalled, and it also lets you use private delimiters and escape sequences in the 
same program. 


The system processes private delimiters before all other characters, including 
control characters such as Ctrl/C. Thus, when you use a standard delimiter 
character as a private delimiter, it does not echo on the terminal. 


Programming Hint 


By combining escape sequences with private delimiters, you can define your own 
function keys without using single character I/O. For example: 


1. Make sure the keypad is in the right mode for your application 
2. Define each function as the PF1 key followed by a character 


3. Define each character as a private delimiter so it does not echo on the termi- 
nal 


For example, you might define PF1 + A as one function and PF1 + M as another 
function. 


Data Passed (Terminal — Private Delimiters) 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
XRB+XRLEN Function code; set to octal 11 for private delimiter mask. 
XRB+XRBC For XRB+XRMOD equals zero, this word must be set to zero. 


For XRB+XRMOD equals one (set private delimiter mask), this 
word is the byte count for the private delimiter bit mask. For 
XRB+XRMOD equals two (read private delimiter mask), this word 
is the buffer length for a buffer into which the mask is to be read. 
For XRB+XRMOD equals one or two, the value of XRB+XRBC 


must be less than or equal to 32. 
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XRB+XRLOC For XRB+XRMOD equals zero, this word must be set to zero. 
For XRB+XRMOD equals one, this word is the address of the 
private delimiter mask. The mask itself can be up to 32 bytes 
long (32 bytes = 256 bits). Each bit in the mask represents an 
ASCII character (see Table 3-8). Setting a bit indicates that the 
associated ASCII character is to serve as a private delimiter. For 
XRB+XRMOD equals two, this word is the address of a buffer into 
which the terminal’s private delimiter mask is to be read. 


Table 3-8: Private Delimiter Masks 


Octal Byte: Byte Value 
Value ASCII Character address+n Bit Octal Decimal 
0+ NUL =O 0 1 1 
SOH 0 2 2 
2 STX 0 2 4 4 
3 HTX (Ctrl/C) 0 3 10 8 
4 EOT 0 4 20 16 
5 ENQ 0 5 40 32 
6 ACK 0 6 100 64 
7 BEL 0 7 200 128 
10 BS (backspace) 1 0 
11 HT (horizontal tab) 1 1 2 2 
12 LF (line feed) 1 2 
13 VT (vertical tab) 1 3 10 8 
14 FF (form feed) 1 4 20 16 
15 CR (carriage return) 1 5 40 32 
16 SO 1 6 100 64 
17 SI (Ctrl/O) 1 7 200 128 
20 DLE 2 0 1 
21 DC1 (Ctrl/Q) 2 1 2 2 
22 DC2 2 2 
23 DC3 (Ctrl/S) 2 3 10 8 
24 DC4 2 4 20 16 
25 NAK (Ctri/U) 2 5 40 32 
26 SYN 2 6 100 64 
27 ETB 2 vi 200 128 
30 CAN 3 0 1 
31 EM 3 1 2 2 
32 SUB (Ctrl/Z) 3 2 4 
33 ESC (ESCAPE) 3 3 10 8 
34 FS 3 4 20 16 | 
35 GS 3 D 40 32 | 


+ Octal code 0 can be used only for terminals opened in binary mode because nulls are ignored in 
normal mode. 


(continued on next page) 
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Table 3-8 (Cont.): 


Private Delimiter Masks 


Octal Byte, poe Vas 
Value ASCII Character address+n Bit Octal Decimal 
36 RS 3 6 100 64 
37 US 3 7 200 128 
40 SP (space) 4 0 

Al I 4 1 2 2 
42, ‘ 4 2 

43 # 4 3 10 8 
44 $ 4 4 20 16 
45 % 4 5 40 32 
46 & 4 6 100 64. 
47 ’ (apostrophe) 4 7 200 128 
50 ( 5 0 1 1 
51 ) 5 1 2 2 
5A , (comma) 5 4 20 16 
55 — (dash/minus) 5 5 40 32 
56 . (period) 5 6 100 64 
57 / 5 7 200 128 
60 0 6 0 

61 1 6 1 

62 2 6 2 

63 3 6 3 10 8 
64 4 6 4 20 16 
65 5 6 5 40 32 
66 6 6 6 100 64 
67 7 6 7 200 128 
70 8 7 0 

71 9 7 1 2 
72 7 2 4 

73 : 7 3 10 

74 < 7 4 20 16 
75 = 7 5 40 32 
76 > 7 6 100 64 
77 ? 7 7 200 128 
100 @ 10 (8) 0 

101 A 10 (8) 1 

102 B 10 (8) 2 

103 C 10 (8) 3 10 8 
104 D 10 (8) 4 20 16 
105 E 10 (8) 5 40 32 


(continued on next page) 
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Table 3-8 (Cont.): 


Private Delimiter Masks 


-—— OO OOOO 


Octal Byte, 
Value ASCII Character address+n 
106 F 10 (8) 
107 G 10 (8) 
110 H 11 (9) 
111 I 11 (9) 
112 J 11 (9) 
113 K 11 (9) 
114 L 11 (9) 
115 M 11 (9) 
116 N 11 (9) 
117 O 11 (9) 
120 P 12 (10) 
121 Q 12 (10) 
122 R 12 (10) 
123 S 12 (10) 
124 «oT 12 (10) 
125 U 12 (10) 
126 V 12 (10) 
127 W 12 (10) 
130 Xx 13 (11) 
131 Y 13 (11) 
132 Z 13 (11) 
133 [ 13 (11) 
134 \ 13 (11) 
135 ] 13 (11) 
136 “ or * 13 (11) 
137 _ore 13 (11) 
140 ~ (grave accent) 13 (12) 
141] a 13 (12) 
142 b 13 (12) 
143 c 13 (12) 
144 d 13 (12) 
145 e 13 (12) 
146 f 13 (12) 
147 g 13 (12) 
150 h 15 (13) 
151 i 15 (13) 
152 j 15 (13) 
153 k 15 (13) 
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Byte Value 
Bit Octal Decimal 
6 100 64 
7 200 128 
0 1 
1 2 2 
2 4 
3 10 8 
4 20 16 
5 40 32 
6 100 64 
7 200 128 
0 1 
1 2 2 
2 4 
3 10 8 
4 20 16 
5 40 32 
6 100 64 
7 200 128 
0 1 
1 2 2 
2 4 
3 10 8 
4. 20 16 
5 40 32 
6 100 64 
7 200 128 
0 
1 2 2 
2 4 4 
3 10 8 
4 20 16 
5 40 32 
6 100 64 
7 200 128 
0) 1 
1 2 2 
2 4 
3 10 8 


(continued on next page) 


Table 3-8 (Cont.): 


Octal Byte, 
Value ASCII Character 
154 ] 15 (13) 
155 m 15 (13) 
156 n 15 (13) 
157 ) 15 (13) 
160 p 16 (14) 
161 q 16 (14) 
162 Yr 16 (14) 
163 8 16 (14) 
164 t 16 (14) 
165 u 16 (14) 
166 Vv 16 (14) 
167 Ww 16 (14) 
170 x 17 (15) 
171 y 17 (15) 
172 z 17 (15) 
173 { 17 (15) 
174 | (vertical) 17 (15) 
175 } 17(15) 
176 ~ (tilde) 17 (15) 
177 DEL (RUBOUT) 17 (15) 
200- 
377 
/NOEIGHT_BIT characteristic. 

XRB+XRCI 
XRB+XRBLKM 
XRB+XRBLK 

indicated by XRB+XRCI. 
XRB+11 

zero. 
XRB+XRTIME 


Private Delimiter Masks 


address+n 


se) 
o> 


RD or FP HO NO KB CON HF TF fF WHO WO KW TO NN TD TF Kf 


7 


40 
100 
200 


Byte Value 


Decimal 


64 
128 


Can only be used for terminals with the /EIGHT_BIT characteristic set or open 
in binary mode; the 8th bit is cleared in normal mode for terminals with the 


Channel number times two. When this byte equals zero, it indi- 


cates the job’s keyboard. When this byte does not equal zero, a 
keyboard must be open on the indicated channel. 


Handler index for terminals; TTYHND (octal value is 2). 
Specifies the keyboard number that the subfunction is to take 


place on. If this byte and the byte at XRB+11 equal zero, then 
the subfunction is performed on the terminal open on the channel 


Flag byte. If bit 7 of this byte is set (byte equals 128), it indi- 
cates that the keyboard number at XRB+XRBLK is rea]. (When 
XRB+XRBLK is zero, this bit set indicates that KBO: is the de- 
sired terminal. If this bit is cleared and XRB+XRBLEK is zero, 
it indicates that the keyboard open on the channel indicated at 
XRB+XRCI is the desired terminal.) All other bits must equal 


This word must be set to zero. 
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XRB+XRMOD 


Subfunction code: 


0 = Clear private delimiter mask. 
1 = Set private delimiter mask. 
2 = Read private delimiter mask. 


Once set, private delimiters remain in effect for a terminal until 
cleared (XRB+XRMOD = 0) or until implicitly cleared by: 


e Deassigning or closing the terminal 
e Killing the job or hanging up the line 
e Keyboard monitor read (negative wait time on .READ) 


Note that clearing the delimiter mask to all zeros is not the same 
as issuing the clear subfunction (XRB+XRMOD = 0). Use the clear 
subfunction to free system resources used when any mask is set. 


Data Returned (Terminal—Private Delimiters) 


Except for a 


possible error in byte 0 of the FIRQB, the private delimiter subfunc- 


tions of SPEC do not return any meaningful data. 


Errors (Term 


BADCNT 


BSERR 
ERRERR 
NOBUFS 


NOSUCH 


NOTOPN 
PRVIOL 
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inal—Private Delimiters) 


One of the following conditions has occurred: 


e Byte count at XRB+XRBC does not equal zero or is greater than 32 
e Invalid address at XRB+XRLOC 


An illegal channel number is specified at XRB+XRCI. 

Multiple delimiter feature is not included in the monitor. 

The monitor needs to expand its internal buffer space, but memory is not 
available; a retry may succeed. 


You are trying to read the private delimiter mask, but no private delimiters 
are set. 


The channel specified at XRB+XRCI is not open. 


Privilege violation; one of the following conditions has occurred: 


e Job does not own the specified keyboard and does not have the required 
privilege 
© Subfunction code at XRB+XRMOD is not 0, 1, or 2 


e Function code is not 0 through 7 or 11 (returned for all .SPEC calls for 
terminals) 


e An illegal terminal number is specified at XRB+XRBLK 
e The device open on the channel specified at XRB+XRCI is not a terminal 


3.28 .STAT — Return Job Statistics 


Form 
STAT 


Function 


The .STAT directive returns current statistics on the job to the XRB. 


Privileges Required 


TUNE is required to read the current run priority or run burst settings. 


Data Passed 


The .STAT directive does not pass any meaningful data. 


Data Returned 


Mne- Octal 
monic Offset 


XRB+XRLEN 


XRB+XRBC 
XRB+XRLOC 


XRB+XRCI 


XRB+XRBLK 


XRB 
Octal Mne- 
Offset monic 


The current size of the user job image for this job, in K words. If 
I&D Space is enabled, this is the size of only the D-Space of the 
task. 


The size of the current run-time system for this job, in K words. 


The current private memory maximum for the user job image, in 
K words. If the job has an unlimited memory maximum or if its 
private memory maximum is larger than the possible maximum 
size allowed by its current run-time system, then the value re- 
turned here is the maximum size possible for the current run-time 
system, in K words. If the job’s private maximum is less than the 
run-time system minimum, then the value returned here is the 
run-time system’s minimum size (see the .CORE directive). In 
all cases, this value represents the maximum size of the user job 
image under its current run-time system. 

The maximum job image size possible (under the current run- 
time system), in K words. If I&D Space is enabled, this is the 
maximum size to which D-Space can expand. 

The job’s current PPN is returned here. The programmer number 
is returned as a binary value in the low byte XRB+XRBLK), the 
project number as a binary value in the high byte (XRB+11). If 
the job is not logged in, a value of 0 is returned here. 
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XRB+XRTIME 


XRB+XRMOD 


Errors 


The job’s current run priority (if caller has TUNE privilege; 
otherwise, .STAT returns zero). Run priority may range from 
-128, indicating a suspended job, to +127, the highest priority. 
The monitor schedules jobs for time-shared execution according 
to this priority. When a user first logs in to RSTS/E, LOGIN is 
run with priority 0. LOGIN sets the user’s job run priority to -8. 
Only in unusual cases should the run priority be changed. It can 
be changed by a user with TUNE privilege for any job with the 
SET JOB/PRIORITY command. It can also be changed with the 
UU.PRI subfunction of the .UUO directive. It can be modified by 
the job by one-half step (4) with the .SET and .CLEAR directives. 
The special-case value of -128 indicates that the job is never 
scheduled to run; it is suspended. 


The job’s current run burst (if caller has TUNE privilege; other- 
wise, .STAT returns zero). The run burst is the amount of time 
that the job is allowed to execute compute-bound before the next 
job in the schedule is given control. The units of run burst are 
1/60ths or 1/50ths of a second, depending on the clock in use 
and/or the line frequency. (Systems running with the KW11-P 
clock at crystal speeds, rather than at line frequency, or 11/83, 
11/84, 11/93, or 11/94 systems with 800 Hertz clocks, have a run 
burst unit of 1/50th of a second. Otherwise, if the system is oper- 
ating with a 60 Hz power line, one run burst unit equals 1/60th 
of a second.) The range of values for run burst is from 1 to 127. 
When a job is created, the monitor sets the run burst to a value of 
six. This value can be modified by the system manager for a par- 
ticular job with the SET JOB/RUN_BURST command. It can also 
be modified with the UU.PRI subfunction of the .UUO directive. 


No errors are possible on this directive. 


Example 


Since the .STAT directive does not pass any data to the monitor, the call is simply: 


STAT 


3.29 .TIME — Return Timing Information 


Form 
. TIME 


Function 


The .TIME directive returns job timing information: elapsed CPU time, elapsed 
time connected to a user terminal (channel 0), elapsed device time, and memory 
utilization. 


Privileges Required 


None. 


Data Passed 


The .TIME directive does not pass any meaningful data. 


Data Returned 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | low 16 bits of elapsed CPU time, .1 sec. 0 XRLEN 
3 | elapsed connect time to channel 0, min. 2 XRBC 
5 | low 16 bits of memory utilization, KCTs | 4 XRLOC 
7 elapsed device time, minutes 6 XRCl 
11 high 16 bits of elapsed CPU time, .1 sec. 10 XRBLK 
13 ETALLAATAT AIT IAAT I Ed 12 
15 | high 16 bits of memory utilization, KCTs 14 XRMOD 
XRB+XRLEN The low-order 16 bits of the job’s elapsed CPU time, in tenths of a 
second of CPU utilization. 
XRB+XRBC The elapsed time that the job has been connected to a channel 0 
terminal, in minutes. 
XRB+XRLOC The low-order 16 bits of the job’s memory utilization, in kilo- 


core-ticks (KCTs). A kilo-core-tick is the use of 1K of memory for 
one-tenth of a second. 


XRB+XRCI The job’s elapsed device time. Device time is the use of an allo- 
catable device for one minute. If a job owns two devices for one 
elapsed minute, then two units of device time are accrued. 


XRB+XRBLK The high-order 16 bits of the job’s elapsed CPU time (see 
XRB+XRLEN). 

XRB+XRMOD The high-order 16 bits of the job’s memory utilization (see 
XRB+XRLOC). 
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Errors 
No errors are possible with the .TIME directive. 


Example 
Since the .TIME directive does not pass any data, the call is simply: 
TIME 


3-228 .TIME 


3.30 .TTAPE — Enter Tape Mode 


Form 
.TTAPE 


Function 


The .TTAPE directive enters tape mode on the job’s terminal (channel 0). Use 
this directive when it is necessary to read data from the low-speed paper tape 
reader available on some terminals. Make sure the terminal is open on channel 
0, and call this directive before the .READ directive. Three things happen: 


e No incoming characters are echoed, preventing needless output at the termi- 
nal while the tape is being read. 


e The DELETE character (ASCII code 177) is ignored, rather than deleting the 
previous character. 


e A LINE FEED character (ASCII code 012) is not automatically appended to 
an incoming RETURN (ASCII code 015). 


The .TTECH directive returns character processing to normal on channel 0. 


Privileges Required 


None 


Data Passed 
The .TTAPE directive does not pass any data. 


Data Returned 
The .TTAPE directive does not return any data. 


Errors 
DETKEY Channel 0 is not currently available for this job; it is running detached. 


Example 
Since the .TTAPE directive does not pass or return any data, the call is simply: 


.TTAPE 
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3.31 .TTDDT — Disable Full-Line Buffering 
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Form 
.TTDDT 


Function 


The .TTDDT directive disables the monitor’s usual practice of buffering a full line 
of data from the user’s terminal (channel 0) before passing it on to the job on a 
.READ directive. 


The monitor accepts data typed at a user terminal and stores it in a buffer 
until the job associated with the terminal reads the data. Normally, a .READ 
causes the monitor to pass a line to the job’s buffer. (A line is any number of 
characters ending with a RETURN, LINE FEED, ESCAPE, FORM FEED, or 
Ctrl/D combination.) If a full line is not in the monitor’s buffer, the monitor stalls 
the job until it gets a delimiter and then awakens the job and passes the line on 
to the job’s buffer. 


The .TTDDT directive tells the monitor that, when the next .READ on the user’s 
terminal is issued, it is to pass on whatever is currently in the monitor’s buffer, 

whether or not a delimiter has been typed. If no characters are in the monitor’s 
buffer, the job is stalled until at least one character has been typed. 


.TTDDT is a one-shot directive: it affects only the next .READ on the user’s 
terminal. If you want to do this type of input pone eae you must execute a 
.TTDDT before each .READ. 


This type of input is useful when you want to respond to each character that a 
user types. (Note that more than one character may be in the monitor’s buffer. If 
you really want only one character, use .TTDDT before each .READ, and define 

a 1-character input buffer for the READ.) For example, the ODT utility (see 

the ODT Reference Manual) uses this capability to accept commands without 
requiring that you type a delimiter. This type of input puts a high load on the 
system; Digital does not recommend its use except in unusual circumstances. 


Privileges Required 


None 


Data Passed 
The .TTDDT directive does not pass any data. 


Data Returned 
The .TTDDT directive does not return any data. 


Errors 
DETKEY Channel 0 is not currently available for this job; the job is running detached. 


Example 


Since the .TTDDT directive does not pass any data, the call is simply: 
.TTDDT 


3.32 .TTECH — Undo .TTAPE or .TTNCH 
Form 
.TTECH 


Function 


The .TTECH directive causes the monitor to resume normal character input 
processing on channel 0 when it has been disabled with either a .TTAPE directive 
or a .TTNCH directive. 


Privileges Required 


None 


Data Passed 
The .TTECH directive does not pass any data. 


Data Returned 
The .TTECH directive does not return any data. 


Errors 
DETKEY Channel 0 is not available for this job; the job is running detached. 


Example 
Since the .TTECH directive does not pass any data, this call is simply: 
.TTECH 
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3.33 .TTNCH — Stop Echo 
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Form 
.TTINCH 


Function 


The .TTNCH directive disables terminal echo on the job’s terminal (channel 0). 
That is, whatever the user types is accepted, but it is not echoed back for display 
on the terminal. Otherwise, all normal character processing occurs. (The .TTECH 
directive returns character processing to normal on channel 0.) 


Privileges Required 


None 


Data Passed 
The .TTNCH directive does not pass any data. 


Data Returned 
The .TTNCH directive does not return any data. 


Errors 
DETKEY Channel 0 is not available for this job; the job is running detached. 


Exampie 
Since the .TTNCH directive does not pass any data, the call is simply: 
.TTNCH 


3.34 .TTRST — Restart Output 


Form 
.TTRST 


Function 


The .TTRST directive restarts program output to the user’s terminal when such 
output has been stopped by the user’s typing a Ctrl/O or Ctrl/C. 


Terminal service in the RSTS/E monitor maintains a "discard all program output" 
indicator for each terminal. When this indicator is set, the driver ignores a 
.WRITE directive to the terminal rather than display the data at the user’s 
terminal. When the indicator is clear, a .WRITE to the terminal is processed 
normally. The .TTRST directive clears this indicator. 


The driver sets the indicator when the user enters a Ctrl/C combination. It 
reverses the indicator when the user enters a Ctrl/O combination. A .READ 
directive to the user’s terminal clears the indicator. 


One use of .TTRST is in run-time systems with keyboard monitors. By issuing 
.TTRST before displaying any prompt, you can ensure that the prompt is actually 
displayed at the user’s terminal. 


Privileges Required 


None 


Data Passed 
The .TTRST directive does not pass any data. 


Data Returned 
The .TTRST directive does not return any data. 


Errors 


DETKEY The user’s terminal is not currently available for this job; the job is running 
detached. 


Example 
Since the .TTRST directive does not pass any data, the call is simply: 
.TTRST 
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3.35 .ULOG — Modify User Logical 
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Form 
.ULOG 


Function 


The .ULOG directive has three subfunctions. You select the particular action 
desired by setting a function field in the FIRQB (at offset FQFUN). Table 3-9 
lists the subfunctions by function code. The following sections describe the 
subfunctions in alphabetical order. 


Table 3-9: Summary of .ULOG Subfunctions 


FQFUN 

Value 

(Octal) Mnemonic Action Performed 

12 UU.ASS Allocate, reallocate, assign, or reassign a device, or assign or 
list user logicals 

13 UU.DEA Deallocate a device or deassign a user logical 

14 UU.DAL Deallocate all devices and deassign all user logicals 


Privileges Required 
See the descriptions of each .ULOG subfunction. 


3.35.1 UU.ASS (Allocate/Reallocate a Device, or Assign or List User Logical) 


Form 


MOVB #UU..ASS, FIROB+FQOFUN 
(set up FIRQB and XRB) 


- ULOG 


Function 
The UU.ASS subfunction of .ULOG lets you do one of four things: 


e Allocate a device to a job. If you assign a LAT port for host-initiated connec- 
tions, this directive initiates a connection to the server currently assigned to 
the port. 


e Reallocate a device to another job. 
e¢ Enter a user logical. This feature lets you: 


— Assign a logical name to a device. The monitor then uses this assignment 
for logical-to-physical device translation by the .FSS directive. 


— Associate a PPN with a particular logical name. This user logical PPN 
is used if the associated logical name (but no PPN) is found in a string 
scanned by .FSS. Use this feature if you want to override a system-wide 
logical name with an associated PPN. For example, the logical name LB is 
commonly associated with a disk on the public structure and some specific 
PPN (usually [1,1]). With this feature, you can set up a different device 
and PPN for the logical name LB. 


— Assign a PPN to be substituted for an at sign (@) character encountered 
in a file specification string scanned by an .FSS directive. 


— Assign a protection code to be used as a default if no protection code is 
specified in a file specification string translated by an .FSS directive. 


e List all assigned user logical names by index. 


NOTE 


Assigning user logicals assigns values to the USRPPN and USRPRT 
areas in the low 1000 bytes of virtual memory and to the extended 
logical area of the job header (see Chapter 2). 


CAUTION 


Digital strongly recommends you do not write or run programs that 
directly manipulate user logicals in low core. Such programs may 
perform erratically. Instead, use the .ULOG directive. 


Privileges Required 


No privileges are required to manipulate user logicals or deallocate a device. 
DEVICE is required to allocate a restricted device. HWCTL is required to seize a 
device or reallocate a device to a job in another account. 
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Data Passed — Allocate/Reallocate Device 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 PILE TAITITII TIT ITT TT 0 
rorun s | wuase@oniay | ~d 
5 | LETITIA IAT 4 
11 [must be 0 10 FONAM 
13 | FETILAT SI ALAL TAAL I La | 12 
15 DOS or ANS in RAD50 format (1 word) 14. FQEXT 
17 PELE ITTII TIT T TTT 16 
21 | VALTAA IT LATTA AT ATA A 20 
25 EEALTAAAL TELAT ET ald CA 24 
27 (must be 0) 26 
31 device name (2 ASCII characters) 30 FQDEV 
35 TITALALTSLGDA LAIST EF 34 
37 FILITITALT AA TIA TAT 36 

FIRQB+FQFUN The function code UU.ASS (octal value = 12). 

FIRQB+FQNAM1 For allocating a device, the two bytes beginning here must 
equal zero. For reallocating a device, this byte is the job 
number to which the device is to be reallocated. The byte at 
FIRQB+FQNAM1+1 must equal zero. If you do not have HWCTL 
privilege, you can reallocate a device only to a job that is logged in 
to the same account as your current account. 

FIRQB+FQEXT For allocating or reallocating a magnetic tape device, this word is 
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either DOS or ANS (in RAD50 format) to indicate DOS or ANSI 


label format for the magnetic tape drive. 


FIRQB+FQMODE 


FIRQB+FQDEV 


FIRQB+FQDEVN 


This word contains the mode to use when allocating the device. 
Valid modes are: 


Mode 
100001 


100002 


100004 


Description 


Used to allocate a device that is currently allo- 
cated to (but not opened by) another user. This is 
a snagging allocation, available to users with the 
HWCTL privilege. 

Only used when allocating a LAT port and used 
to tell the LAT driver that the request to initiate 
the connection should not be queued if the remote 
port is not available. 


Only used when allocating a LAT port and used to 


tell the LAT driver that the request to initiate the 
connection should be queued if the remote port is 
not available. 


Used when you do not want a snagging allocation 
and when you want the LAT driver to use the 
port’s default queueing setting. 


Device name to be allocated or reallocated, specified as two ASCII 
characters. If this word is zero, the public disk structure is 


assumed. 
Device unit number, passed as a binary value in byte FIRQB+FQDEVN. 


A nonzero value in byte FIRQB+FQDEVN+1 indicates an explicit 
device unit number. A zero value in byte FIRQB+FQDEVN+1 


indicates no device unit number. 


NOTE 


The XRB should be cleared to zeros for an allocate or reallocate device 


operation. 
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Data Passed — Enter User Logical 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LEAT ITIP TTA | 
UU.ASS (= octal 12) | Las 


1 


FQFUN 3 


5 4 FQFIL 


LAAT TALE LY no-replace flag 


7 6 FQOPPN 


11 10 FQNAM1 


user logical device name in RAD50 format 


(5 words) 


| PAATIAALITAALTAA ET AEE 
LALTAAPAELSALUA ELL LAG 
protection code 255=assign prot. code 


device name (2 ASCII characters) 


FEAT TEA TLAG ATE TET TT 
| LALIT ALITPAGALAAT ES 


FIRQB+FQFUN The function code UU.ASS (octal value = 12). 


FIRQB+FQFIL The no-replace flag. Set bit 7 of this byte to 1 to avoid replacing 
existing user logicals. 


FIRQB+FQPPN The PPN for those features that use a PPN (see the discussion 
under Function at the beginning of this section). For a user- 
assignable PPN, this is the PPN to be used to replace an @ sign in 
a string parsed by an .FSS directive. In this case, the two bytes at 
FIRQB+FQNAM1 and FIRQB+FQNAMI1+1 must be zero. If the 
four bytes FIRQB+FQNAM1 through FIRQB+FQNAM1+3 contain 
a logical device name, and a PPN is to be associated with that 
name, specify the PPN here. If no PPN is to be associated with 
the logical device name, set this word to zero. 


FIRQB+FQNAM1 To assign a user logical name to a device, set the five words 
beginning here to the logical name, in RAD50 format. Otherwise, 
set these bytes to zero. 


25 


FQPROT 27 26 FQPFLG 


31 30 FQDEV 


33 32 FQDEVN 


35 


37 


FIRQB+FQPFLG To assign a user-assignable default protection code, set this byte 
to nonzero. (See FIRQB+FQPROT. ) 
FIRQB+FQPROT The protection code to be used as a default if no protection code 


is specified in a string scanned by an .FSS directive. The byte 
at FIRQB+FQPFLG must be nonzero, and the two words at 
FIRQB+FQPPN and FIRQB+FQNAM1 must be zero. 


FIRQB+FQDEV Device name for assigning a logical name to be associated with a 
device. Specify the device as two ASCII characters. If this word is 
zero, the public disk structure is assumed. 
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FIRQB+FQDEVN 


Mne- Octal 


monic Offset 


XRB+XRLEN 


XRB+XRBC 
XRB+XRLOC 


Data Returned 


FIRQB 
FIRQB+FQFIL 


Errors 


Device unit number for assigning a logical name to be asso- 
ciated with a device. The device unit number is passed as a 
binary value in byte FIRQB+FQDEVN. A nonzero value in byte 
FIRQB+FQDEVN+1 indicates an explicit device unit number. A 
zero value in byte FIRQB+FQDEVN+1 indicates no device unit 
number. 


XRB 
Octal Mne- 
Offset monic 


. 
: 
: 
; 


If the user logical information is in its standard location 
(USRPPN, USRPRT, and USRLOG), this word is passed as zero. 
If some nonstandard set of locations is being used, then specify the 
length (in bytes) of that information, here. Thus, when the user 
logical information is in a nonstandard location, this word must be 
at least four (for user-assignable PPN and default protection code). 


The length of the information (same as the word at XRB+XRLEN). 


If the word at XRB+XRLEN is nonzero, then this word defines 
the starting location for the user logical information (the default 
PPN). See Chapter 2 for a description of the order and format of 
the information created by .ULOG. 


The error code (if any). 


The previous owner of the device as follows: 


e If you own a device already and allocate it, UU.ASS returns 
your own job number. 


e If you seize a device, you can see who you seized it from. 


e Ifthe value in FIRQB+FQFIL is zero, then you know that the 


device was not previously owned. 


BADCNT This error has two possible causes: 


The length specified at XRB+XRLEN and XRB+XRBC must be 4 + 8n, 
where n = 0, 1, 2, 3, or 4. If it is not, this error is returned. (Other 
lengths are not valid user logicals.) 


The value at XRB+XRLOC is odd. 
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BDNERR An attempt was made to reallocate a device to a nonexistent job. This error 
can occur only for a reallocate call. 


FIEXST The logical name specified in FIRQB+FQNAM1 already exists and the 
no-replace flag in FIRQB+FQFIL is set. The logical name is not replaced. 


INUSE For allocating or reallocating a device, the specified device is currently 
open or has an open file. For assigning a user logical, no space is currently 
available for storing the information. 


NODEVC The device name specified at FIRQB+FQDEVN is a logical device name for 


which a physical device is not currently allocated. 


NOTAVL The device specified exists on the system, but the operation failed for one of 
the following reasons: 


e The device is currently reserved by another job (see description of 
FIRQB+FQMODE). . 

© Ownership of the device requires DEVICE privilege, which the user 
does not have. 


e The device or its controller is disabled. 
e The device is a keyboard line for a pseudo keyboard only. 

PRVIOL You do not have the required privileges and tried to reallocate a device to a 
job that is logged in to an account other than your current account. 


NOBUFS No buffers available to initiate the connection to the terminal server. 


Example 


The following code allocates the user logical name OUT to the public disk struc- 
ture. Assume that the FIRQB and XRB have been previously cleared to zero. For 


example: 

MOVB #UU .ASS, FIRQB+FQFUN ; Set function code 
MOV #*ROUT, FIRQB+FQNAM1 ; Set logical name as 
MOV #°R , FIRQB+FQNAM1+2 : two words RAD50 

» VLOG 
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Data Passed—List User Logicals 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


| RU ereeheeeeeRcaces 
UU.ASS (= octal 12) | Reeeee aan 


1 


FQFUN 3 


4 FQEFIL 


6 FQPPN 


10 FQONAM1 


(must be 0) : 
[itnmiiniein —_| 
[innininnii 


PATTI PATA TI TAA IAAI 


(must be 0) TALI ATLL SY 


iii 


FIRQB+FQFUN The function code UU.ASS (octal value = 12). 


FIRQB+FQFIL The index number of the logical name to return. Passing a 1 
returns information about the first assigned user logical, passing a 
2 returns information about the second assigned user logical, and 
so on. 


FQPROT 27 


31 


33 


35 


37 
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Data Returned—List User Logicals 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


. , 
7 | project number | programmer number 6 FQPPN 
11 10 FQNAM1 
13 | 12 
user logical device name in RAD50 format 
15 (5 words) 14 
17 16 
21 20 
FIRQB+FQPPN The PPN assigned to this user logical, or zero if no PPN was 
assigned. 
FIRQB+FQNAM1 The five words beginning here contain the returned user logical 
name in RAD 50 format 
FIRQB+FQDEV The physical device name assigned to this user logical. If no 
device name was assigned, this word and the next word both 
contain zero. 
FIRQB+FQDEVN Device unit number for assigning a logical name to be asso- 
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ciated with a device. The device unit number is passed asa_ | 
binary value in byte FIRQB+FQDEVN. A nonzero value in byte 
FIRQB+FQDEVN+1 indicates an explicit device unit number. A 
zero value in byte FIRQB+FQDEVN+1 indicates no device unit 
number. 


3.35.2 UU.DAL — Deallocate All Devices and Deassign All User Logicals 


Form 


MOVB #UU .DAL, FIRQB+FQFUN 


(set up FIRQB and XRB) 


.- ULOG 


Function 


The UU.DAL function of .ULOG deallocates all devices and deassigns all user 
logicals for the calling program. 


Privileges Required 


None 


Data Passed 


FIRQB 

Mne- Octal Octal Mne- 
monic Offset Offset monic 

, . 
FQFUN 3 | UU.DAL (=octal 14) 2 

. 

37 CAD EA LAY PAPAL LAT TTA AD 36 

FIRQB+FQFUN The function code UU.DAL (octal value equals 14). 
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FIRQB+FQFIL The deassign-only flag. Set this byte to 1 to deassign all user 
logicals without deallocating devices. 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


length of user logical information | 


0 XRLEN 


2 XRBC 


| starting address for user logical info 


4 XRLOC 


6 


PETTITT AAT AT TT ada 
LVI TALATAT AT IT TA AT I AY 
CAV LLALEL ITA T TLE Lk 


LIITIIIITII ITT TTT 


10 


length of user logical information 


12 


14 


XRB+XRLEN If the user logical information is in its standard location 
(USRPPN, USRPRT, and USRLOG), set this word to zero. If 
some nonstandard set of locations is being used, then specify the 
length (in bytes) of that information. 


XRB+XRBC The length of the information (same as the word at XRB+XRLEN). 


XRB+XRLOC If the word at XRB+XRLEN is nonzero,.then this word defines 
the starting location for the user logical information (the default 
PPN). See Chapter 2 for a description of the order and format of 
the information created by .ULOG. 


Data Returned 
The UU.DAL subfunction of .ULOG does not return any meaningful data. 


Errors 


BADCNT This error has two possible causes: 


e The length specified at XRB+XRLEN and XRB+XRBC must be 4+8n, 
where n = 0, 1, 2, 3, or 4. If it is not, this error is returned. (Other 
lengths are not valid user logicals.) 


°e The value at XRB+XRLOC is odd. 


Example 


The following code deallocates all devices and deassigns user logicals for the 
current job. The user logical information is in its standard location. For example: 


MOVB #UU .DAL, FIROB+FQOFUN 
CLR XRB+XRLEN 

CLR XRB+XRBC 

CLR XRB+XRLOC 

. ULOG 
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3.35.3 UU.DEA — Deallocate a Device or Deassign a User Logical 


Form 


MOVB #UU .DEA, FIRQB+FQFUN 


(set up FIRQB) 


- ULOG 


Function 


The UU.DEA subfunction of .ULOG deallocates a device from the current job 
(releases it for use by other jobs) or deassigns a user-logical assignment. 


Privileges Required 


None 


Data Passed for Deallocate Device 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset | Offset monic 
. . 
FQFUN 3 UU.DEA costal 13) 2 
; 
27 (must be 0) | 26 FQPFLG 
31 device name (2 ASCII characters) 30 FQDEV 
33 device unit number | 32 FQDEVN 
FIRQB+FQFUN The UU.DEA function code (octal value equals 13). 
FIRQB+FQDEV The name of the device to be deallocated; two ASCII characters. 
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FIRQB+FQDEVN 


The device unit number is passed in this byte, in binary. A 
nonzero value in FIRQB+FQDEVN+1 indicates an explicit device 
unit number. A zero value in FIRQB+FQDEVN+1 indicates no 
device unit number. 


NOTE 


The XRB should be cleared to zeros for deallocating a device. 


Data Passed for Deassign User Logical 


Mne- Octal 
monic Offset 


FIRQB 


Octal Mne- 
Offset monic 


1 ELA LALAIALL EIA TTS LEGA 0 
FQFUN 3 | UU.DEA (=octal 13) LEITH TA 2 
. , 
11 | 10 FQNAM1 
13 12 
user logical device name in RAD50 format 
15 (5 words) 14 
17 16 
21 20 
27 <>0,deass def prt cde | 26 FQPFLG 
FIRQB+FQFUN The UU.DEA function code (octal value equals 13). 
FIRQB+FQPPN Any nonzero value deassigns any previously assigned default 
PPN. (In this case, set the word at FIRQB+FQNAM1 to zero.) If 
deassigning the default protection code, set this word to zero. 
FIRQB+FQNAM1 The logical device name to be deassigned; five words in RAD50 
format. If deassigning a default. PPN or protection code, set the 
word at FIRQB+FQNAM1 to zero. 
FIRQB+FQPFLG Set this byte to nonzero if deassigning a protection code. 
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XRB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
: . 
XRB+XRLEN Must be zero. If the user logical information is in its standard 


location (USRPPN, USRPRT, and USRLOG), it will be deassigned. 
If it is in any nonstandard location, UU.DEA cannopt deassign the 
logicals individually. You can clear logical tables in nonstandard 
locations with UU.DAL. 


XRB+XRBC The length of the information (same as the word at XRB+XRLEN). 
XRB+XRLOC Must be zero. 


Data Returned | 


Eixcept for a possible error in byte 0 of the FIRQB, the UU.DEA subfunction of 
-ULOG does not return any meaningful data. 


Errors 


BADCNT This error has two possible causes: 


e The length specified at XRB+XRLEN and XRB+XRBC must be 4+8n, 
where n = 0, 1, 2, 3, or 4. If it is not, this error is returned. (Other 
lengths are not valid user logicals.) 


e The value at XRB+XRLOC is odd. 


NODEVC The device or its type specified at the locations FIRQB+FQDEV and 
FIRQB+FQDEVN is not part of your system configuration. 


Example 
The following code deallocates MT0: from the current job: 


MOVB #UU .DEA, FIRQB+FQFUN > Set function code 
CLR FIRQB+FQNAM1 Clear name 


MOV #"MT, FIRQB+FQDEV ; Set device 

MOVB #0, FIRQB+FQDEVN >; Set unit number 
MOVB #377, FIROB+FQDEVN+1 ; Unit number real 
- ULOG 
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3.36 .UUO — Execute BASIC-PLUS SYS Call 


Form 
.UU0 


Function 


The .UUO directive lets a MACRO program execute the BASIC-PLUS SYS calls 
to the File Processor (FIP). The RSTS/E Programming Manual describes the 
SYS calls. For the MACRO programmer's convenience, the FIRQB formats for 
the calls are shown here; however, for detailed descriptions see the RSTS/E 
Programming Manual. 


Table 3-10 summarizes the FIP SYS calls; note that some of the calls are han- 
dled by directives other than .UUO. (.FSS, for example, handles the file name 
string scan in MACRO.) The mnemonic subfunction names are provided by the 
COMMON.MAC prefix file; the decimal values are the BASIC-PLUS FIP call 
subfunction codes and the .UUO subfunction codes that COMMON.MAC relates 
to the mnemonics listed. 


The rest of this section gives the FIRQB formats for data passed and returned for | 
the .UUO subfunctions; the subfunctions are organized in alphabetical order of 
the mnemonics provided by COMMON.MAC. 


Table 3-10: .UUO Subfunctions — Calls to the File Processor (FIP) 


Mnemonic 


UOU.TB3 
UU.SPL 
UU.DMP 
UU.FIL 


UU.ATR 
UU.CCL 

(.FSS) 

(SET) 

(.SET/ .CLEAR) 
(.SET/ .CLEAR) 
UU.LOG 
UU.RTS 


UU.NAM 
UU.DIE 
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BASIC-PLUS 
SYS Call 
Code 
(Decimal) 


Privileges 
That Apply 
None 

r/w file 
SYSIO 


DATES, TUNE 
SYSIO,r/w 


r/w acct 
INSTAL 
None 
TUNE 
None 
TUNE 
SWCTL 


read file INSTAL 


INSTAL 
INSTAL 


read file INSTAL 


INSTAL 
write file 
SHUTUP 


Function 


Get monitor tables—Part III 
Spooling 
Snap shot dump 


File placement and modification 


Read or write attributes 

Add/delete CCL command 

Terminating file name string scan 

Set special run priority 

Drop/regain temporary privilege 
Lock/unlock job in memory 

Set number of logins 

Install run-time system 

Load, remove, or unload run-time system 
Declare default keyboard monitor 
Install resident library 

Load, remove, or unload resident library 
Name run-time system 


System shutdown 


(continued on next page) 
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Mnemonic 


UU.ACT 
UU.DAT 
UU.PRI 
UU.TB2 
UU.BCK 
(.FSS) 
UU.HNG 
UU.FCB 


(internal to 
BASIC-PLUS) 


UU.POK 
(.SPEC) 
(.SPEC) 
UU.TB1 
UU.NLG 
UU.YLG 
UU.PAS 
UU.DLU 
UU.MNT 
UU.LIN 
UU.BYE 
UU.ATT 
UU.DET 
UU.CHU 


UU.ERR 
UU.ASS 

UU.DEA 
UU.DAL 
UU.ZER 
UU.RAD 
UU.DIR 


UU.TRM 
UU.LOK 


UU.CHE 
UU.CNV 


BASIC-PLUS 


SYS Call 
Code 


(Decimal) 


Privileges 
That Apply 
write acct 
DATES 
TUNE 

None 
DATES 
None 


HWCTL 


None 


None 


SYSMOD 

SEND 

SYSIO 

None 

SWCTL 

SWCTL 

write acct 

write acct 
MOUNT 

None 

WACNT EXTQA 
write acct DEVICE 
JOBCTL EXQTA 


write acct JOBCTL 
HWCTL 


None 

DEVICE HWCTL 
None 

None 

DEVICE write acct 
write acct 


DEVICE execute or read 
file 


HWCFG 
DEVICE read file 


TUNE 


None 


+To assign or deassign user logicals, use .ULOG. 


-UUO Subfunctions — Calls to the File Processor (FIP) 


Function 


Accounting dump 

Change system date/time 

Change priority/run burst/job size 
Get. monitor tables—Part II 
Change file backup statistics 

File name string scan 

Hangup a dataset 

Get open channel statistics 


Ctrl/C trap enable 


Poke memory 

Broadcast to terminal 
Force input to terminal 
Get monitor tables—Part I 
Disable logins 

Enable logins 

Create user account 
Delete user account 

Disk pack status 

Login 

Logout 

Attach Reattach Swap console 
Detach 


Change password/quota Kill job Disable 
terminal 


Return error message 
Allocate/reallocate device f 

Deallocate device t 

Deallocate all devices f 

Zero a device 

Read or read-and-reset accounting data 


Directory lookup on index Special mag- 
netic tape directory lookup 


Set terminal characteristics 


Disk directory lookup on file name Disk 
wildcard directory lookup 


Enable/disable disk caching 
Date and time conversion 


(continued on next page) 
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Table 3-10 (Cont.): 


-UUO Subfunctions — Calls to the File Processor (FIP) 


BASIC-PLUS 
SYS Call 
Code Privileges 
Mnemonic (Decimal) That Apply Function 
UU.SLN 21 INSTAL System logical names 
(.MESAG) 22 SEND SYSIO Message send/receive 
UU.SWP 23 r/w files INSTALL Install, remove, list system files 
UU.JOB 24 WACNT JOBCTL Create job 
EXQTA 
UU.PPN 25 DEVICE Wildcard PPN lookup 
UU.SYS 26 JOBCTL TUNE Return job status information 
UU.PRV 28 None Set/clear/read current privileges 
UU.STL 29 HWCTL Stall/unstall system 
UU.3PP 31 None Third-party privileges 
UU.CHK 32 None Check access function 
UU.ONX 33 DEVICE DATES Open next disk file 
r/w files 
UU.CFG 34 HWCFG SWCFG Change system characteristics and device 


HWCTL 


defaults 
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3.36.1 


UU.ACT (Accounting Information Dump) 


Privileges Required 
GACNT or WACNT is required for access to accounting data. 


Data Passed 


FIRQB 


Mne- Octal Octal 


monic Offset 


Mne- 


Offset monic 


FQPPN 


, . 

5 | 4 

: . 
FIRQB+FQPPN Zero in both bytes means the current account. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, The UU.ACT subfunction of 
-UUO does not return any meaningful data. 


Errors 


NOSUCH 
PRVIOL 


The account specified does not exist. 


A caller with GACNT privilege specified an account outside the caller’s 


group. 
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3.36.2 UU.ASS (Allocate/Reallocate Device) 


Privileges Required 
DEVICE is needed to allocate a restricted device. HWCTL is required to seize a 
device or reallocate a device to a job in another account. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


EATALPEE TALL EL ET CELS 
UU.ASS (= 12) PELE LEL ELT 


LITITIITITTTI TAIT TTT 


1 


FQFUN 3 


ELIA TATI EA AA AL AG E ad 


(must be 0) 0,alloc.;<>0,realloc. 10 FQNAMT1 


PETA ETL EEL EIST TALE 


DOS or ANS in RAD50 format (1 word) 14 FQEXT 


ETAT AAALALS ELLA Tal Cd 


EEEPTAAAT ALATA FAVA LS 


22 FQMODE 


PALL EALTLALT AA TATA EAL 
26 FQPFLG 


device name (2 ASCII characters) 30 FQDEV 


IGT AT a 
LEFLE TILT ATT a | 


FIRQB+FQFUN The function code ASSFQ (octal value = 24). 


FIRQB+FQNAM1 This byte is set to zero to indicate an assign; if nonzero, it is used 
as the job number to which the device is to be reassigned. The 
high byte of this word (FIRQB+11) must be set to zero. If you do 
not have HWCTL privilege, you can reassign a device only to a job 
that is logged in to the same account as your current account. 


FIRQB+FQEXT When the device is magnetic tape, this word can contain either 
DOS or ANS in RAD50 format, to indicate DOS or ANSI label 
format for the tape drive. It can also be set to zero to indicate the 
system default for the drive. 


32 FQDEVN 
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FIRQB+FQMODE This word contains the mode to use when allocating the device. 
Valid modes are: 
Mode , Description 
100001 Used to allocate a device that is currently 
allocated to (but not opened by) another user. 
This is a snagging allocation, available to users 


with the HWCTL privilege. 


100002 Only used when allocating a host-initiated LAT 
port and used to tell the LAT driver that the 
request to initiate the connection should not be 
queued if the remote port is not available. 


100004 Only used when allocating a host-initiated 
LAT port and used to tell the LAT driver that 
the request to initiate the connection should be 
queued if the remote port is not available. 


0 Used when you do not want a snagging allo- 
cation and when you want to use the default 
queueing setting on a host-initiated LAT port. 


FIRQB+FQDEV Device name, as two ASCII characters. 


FIRQB+FQDEVN The device unit number is passed here in binary. A nonzero value 
in FIRQB+FQDEVN+1 indicates an explicit device unit number. 
A zero value in FIRQB+FQDEVN+1 indicates no unit number. 


Data Returned 


FIRQB The error code (if any). 
FIRQB+FQFIL The previous owner of the device as follows: 


e If you own a device already and allocate it, UU.ASS returns 
your own job number. 


e If you seize a device, you can see who you seized it from. 


e =6If you reallocate the device, you can see who owned it before 
the reallocation. 


e Ifthe value in FIRQB+FQFIL is zero, then you know that the 


device was not previously owned. 
Errors 


BDNERR Your program attempted to reallocate a device to a nonexistent job. 

INUSE For a reallocate, the specified device is open or has an open file. 

NODEVC Device name at FIRQB+FQDEV is not a valid device name on this system. 
NOTAVL The device specified exists on the system, but the operation failed for one of 


the following reasons: 


e The device is currently reserved by another job (see description of 
FIRQB+FQMODE). 

e The device or its controller is disabled. 

e The device is a keyboard line for a pseudo keyboard only. 

e You do not have DEVICE privilege and the device is restricted. 


PRVIOL You do not have the required privileges and tried to reallocate a device to a 
job that is logged in to an account other that you current account. 


NOBUFS No buffers available to initiate the connection to the terminal server. 
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3.36.3 UU.ATR (Read/Write Attributes) 


Privileges Required (Read/Write File Attributes) 


None 


Data Passed (Read/Write File Attributes) 


Mne—- Octal 
monic Offset 


1 
FQFUN 3 
FQSIZM 5 
7 
11 
13 
15 
17 
21 
23 
25 
27 
31 
33 
35 


37 


FIRQB 
Octal 
Offset 
: 
LI IIIIITT I 2 
; 
6 
10 
12 
14 
attribute data (used only for write) 16 
20 
number of words written = 1-11, as 
specified in byte 5 22 
1 attribute per word 24 
26 
30 
32 
, 
s 


Data Returned (Read/Write File Attributes) 


Other than a possible error in byte 0 of the FIRQB, data is returned on a read 
only (byte 5 of data passed equals zero). 
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Mne- 
monic 


FQFIL 
FQPPN 
FQNAM1 


FQEXT 
FOSIZ 
FQNAM2 
FQMODE 
FQFLAG 
FQPFLG 
FQDEV 


FQDEVN 


FIRQB 


Mne- Octal Octal 


monic Offset 


[nnn | 
: 
Pm) 
| 6 
10 
12 
14 
attribute data 16 
(If file has no attributes, 20 
FIRQB+6 and FIRQB+7 = 0) 
22 
24 
26 
30 
32 
name of run-time system in RAD50 format 34 
(2 words) | 36 


Errors (Read/Write File Attributes) 


BADCNT 
BSERR 
DEVNFES 
NOROOM 


NOTOPN 
PRVIOL 


Mne- 


Offset monic 


FQJOB 


FQPPN 
FQNAM1 


FQEXT 
FQSIZ 
FQNAM2 
FQMODE 
FQFLAG 
FQPFLG 
FQDEV 
FQDEVN 


FQCLUS 


Write only. No value greater than 11 can be specified at FIRQB+FQFIL+1. 
Attributes can be written only on channels 1 through 15. 


Device on which file is open must. be disk. 


Occurs only on a write. The User File Directory (UFD) of the account is full. 
Some files must be deleted to free entries for attributes. 


Channel specified at FIRQB+FQFIL must have file open. 


Job does not have read/write access to the file open on the channel, or a. 


UEFD is open on the channel. 


Privileges Required (Read/Write/Delete Account Attributes) 


No privileges are required to read attributes 1, 2, and 4 to 191 of your own 
account. That is, of the Digital-defined attributes you can read all except the 
password. Of the user-defined attributes (128 to 255) you can read the first 
64. To read attribute 3 (password) or attributes 192 to 255, you need GREAD, 
WREAD, GACNT, or WACNT privilege. 


Read or accounting privileges (GREAD, GACNT, WREAD, or WACNT) are re- 
quired to read accounting data of other accounts. Accounting access (GACNT or 
WACNT) is required to write or delete accounting data of any account. 
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Data Passed (Read/Write/Delete Account Attributes) 


Mne- Octal 
monic Offset 


1 


FQFUN 3 


FQSIZM5 
7 
11 


13 


15 
17 
21 
23 
25 
27 
31 
33 
35 


37 
FIRQB+FQFUN 


FIRQB+FQFIL 


FIRQB+FQSIZM 


FIRQB+FQPPN 


FIRQB+FQNAM1 
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FIRQB 


Octal Mne- 
Offset monic 


0 
2 
attribute type code 4 FQEFIL 

| 10 FQNAMi1 

12 
13 bytes of data 

(only on write) 14 
16 

20 FQNAM2 
22 
24 
: 
; 
: 


The function code UU.ATR (octal value = -31). 


The subfunction code: 


-1 Read account attributes 
-2 Write account attributes 
-3 Delete account attributes 


The attribute type code: 

Look-up by index 

Quotas 

Authorized Privilege Mask 
Password | 
Date/time information 
User name information 
Nondisk quotas 


Aoi WN = © 


The PPN of the account accessed. The project number is in the 
high byte (FQPPN+1), and the programmer number is in the low 
byte (FQPPN). A value of zero defaults to the caller’s PPN. 


The index in a "look-up by index." Look-up by index is speci- 
fied by using a type code of zero in FIRQB+FQSIZM and -1 in 
FIRQB+FQFIL. For programs like BACKUP, it is useful to read 
all the account attributes without having to try each of the 255 
possible type codes. The value n of the index specifies that you 
want nth attribute type. 


FIRQB+FQNAM1+1 


FIRQB+FQDEV 


FIRQB+FQDEVN 


The account attributes to be written to one attribute block. See 
the RSTS/E Internals and Data Structures Manual for details 
about each account attribute. The data is written exactly as 
passed except for attribute types 2 and 4. 


For type 2 (authorized privilege mask), when writing the mask, 
any attempt to turn on privilege bits are ignored if the caller 
does not have the corresponding privilege currently in effect. The 
layout of the 13 bytes are: 


e FIRQB+11—reserved 
e FIRQB+12 through +21—authorized privilege mask 
e FIRQB+22 through +25—reserved 


For type 4 (date/time information), the last login fields are left 
alone unless the fields are currently null. This ensures that any 
logins to an account leave a trace that cannot be tampered with. 
The layout of the 13 bytes are: 


e FIRQB+11—keyboard of last interactive login 


e FIRQB+12,413—date of last interactive login (RSTS internal 
format) 


e FIRQB+14,415—time of last interactive login (RSTS internal 
format) 

e FIRQB+16,+17—date of last password change 

° FIRQB+20,+21—time of last password change and flags 

e FIRQB+22,+23—date of account creation 

° FIRQB+24,+25—expiration date (-1 if none) 

The flags in FIRQB+14,+15 are: 


e Bit 11—no password required ("guest" account) 
e Bits 12-15—reserved 
The flags in FIRQB+20,+21 are: 


e Bit 11—password cannot be looked up ("hashed" password) 

e Bit 12—no dial-up logins allowed 

e Bit 13—no network logins allowed 

e Bit 14—no interactive logins allowed (spawn and batch only) 
e Bit 15—captive account 

If bit 11 is set, then passwords can be up to 14 characters long and 
the system stores them in hashed form. The hash uses parts of 
the date/time attributes; so, altering any bits of bytes FIRQB+16 
through FIRQB+23 (except for the flag bits) renders the password 
useless. The read accounting data directive (UU.RAD) returns two 
zero words if this bit is set. If bit 11 is clear, then passwords can 
be up to six characters long and must consist of uppercase letters 
and numbers; that is, the RAD50 character set. 


The device name passed; two ASCII characters. A value of zero 
indicates "SY", public disk. 

The device unit number passed in binary notation. A nonzero 
value in the high byte of this word (FIRQB+FQDEVN+1) indicates 
an explicit device unit number. A zero value in the high byte 
indicates no unit number. 
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Data Returned (Read/Write/Delete Account Attributes) 


Other than a possible error in byte 0 of the FIRQB, data is returned only on a 
read subfunction (-1 in FIRQB+FQFIL). 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


rrr | ewemipo = 
oe 


0 


2 FQJOB 


4 


6 FQPPN 


10 FQNAM1 


12 


13 bytes of data 


[ie 
[enn 


FIRQB+FQNAMI1 The attribute type code. Contains the type code of the attributes 
just read (same as passed except for lookup by index). 


FIRQB+FQNAMI1+1 The actual attribute data. 


Errors (Read/Write/Delete Account Attributes) 


DEVNES The specified device is not a disk. 


EOF The attribute type not found (read or delete only). The index specified for an 
indexed look-up call is greater than the number of attributes (read only). 


NODEVC The specified device does not exist. 


NOROOM The attribute block did not exist and it cannot be added because the direc- 
tory is full (write only). 


NOSUCH The specified account does not exist. 
NOTMNT The specified disk is not mounted. 


PRVIOL You do not have sufficient privilege for the operation. The disk is write- 
locked (write and delete only). Attempt to delete in the Digital-reserved 
type range (delete only). 


Privileges Required (Read Pack Attributes) 
DEVICE is required if the device specified is restricted. 
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Data Passed (Read Pack Attributes) 


FIRQB | 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. 
rarun 3 | _UUATA(--3n : 
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Data Returned (Read Pack Attributes) 


This call returns information about mounted disks. It is used to obtain the 
characteristics of a disk and the drive the disk is mounted in. 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, . 
: 
. , 
13 Pack Revision Level 12 
21 Pack ID in RAD50 format | 20 FQNAM2 
23 | (in 2 words) | 22 FQMODE 
FIRQB+FQNAM1 The starting device cluster number (DCN) of the MFD. 
FIRQB+12 The pack revision level. 
FIRQB+FQEXT The pack cluster size. 
FIRQB+FQSIZ The pack status/flags. The defined bits are: 


e Bit 9—Pack is initialized "new files first” 

e Bit 11—Pack is initialized to maintain date of last write 
e Bit 12—Pack is initialized as a read-only pack 

e Bit 14—Pack is initialized as a private/system disk 


All other bits are reserved. 


PIRQB+FQNAM2 The pack ID in RAD50 format. The first three characters 
are here and the last three characters are in the next word, 
FIRQB+FQMODE. 

FIRQB+FQFLAG The size of the disk in DCNs. 

FIRQB+FQPFLG The device cluster size. 
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Errors (Return Pack Attributes) 


NOTMNT Device specified is not a logically mounted device. 
NODEVC Device specified is not valid. 
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3.36.4 UU.ATT (Attach/Reattach Job/Swap Console) 


Privileges Required 


DEVICE is required to perform a REATTACH if the terminal is restricted. 
GACNT or WACNT is required to ATTACH to a job outside the caller’s account. 


Data Passed — Attach 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | pis eee eee | oO 
FQFUN 3 | UU.ATT ( 6) Boreeeee s, | 2 
FQSIZM5 | bitmask job number to attach | 4 FQFIL 
11 | password in RADS5O format 10 FOQNAM1 
13 | (2 words) | 12 
15 | or 14 
17 | password in ASCII format 16 
21 | (7 words) | 20 
23 | | 22 
25 | | 24 
27 AA DAAL EL LL TA Ia eld 26 
31 GLEE OTT LER TENE ES 30 
33 TTT | 32 
35 ee Pees 34 
37 RELATE Ge 36 

FIRQB+FQSIZM Bit O must be clear for the attach subfunction. Bit 1 is clear for 
the old password format (RAD50) and set for the new format 
(ASCII). Bit 2 can be set on an attach to suppress the password 
check. If clear, the password is checked if you attach to a job in 
another account. All other bits are reserved. 

FIRQB+FQPPN Zero in both bytes means your PPN. You do not need to include a 
password. If you do not have GACNT or WACNT privilege, you 
can only specify your own PPN. 

FIRQB+FQNAM1 You must include a password if you specify a PPN other than your 


own unless bit 2 is set in FIRQB+FQSIZM. Note that this use of 
the call requires GACNT or WACNT privilege. 


Data Returned 


Other than a possible error in byte 0 of the FIRQB, the attach function of the 
UU.ATT directive does not return any data. 
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Errors 


BADFUO The system returns this error for one of the following reasons: 


e Job executing the cal] has an open channel. 

e §=6©Job executing the call is detached. 

e Job number at FIRQB+FQFIL is not detached. 

e The PPN specified does not match PPN of job to attach. 


e Caller does not have GACNT or WACNT privilege, and the job to attach 
to has a PPN different from that of the caller. 


¢ Password is not valid. 


Data Passed — Reattach 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
{moo : 


Data Returned 


Other than a possible error in byte 0 of the FIRQB, the reattach function of the 
UU.ATT directive does not return any data. 
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Errors 


BADFUO The system returns this error for one of the following reasons: 


e Job number at FIRQB+FQFIL is out of range or no such job exists. 
e Caller is not detached. 
e KB number is out of range. 


e KB is currently allocated, opened, or the console keyboard of some job 
other than the calling job. 


e The terminal is restricted and the caller does not have DEVICE privi- 
lege. 


Data Passed — Swap Console 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[rennin 
[ennai 


FIRQB+FQSIZM Bit O must be set for the swap console subfunction. All other bits 
are reserved. i 


1 


FQFUN 3 
FQSIZM5 4 FQEFIL 
7 


11 


13 


15 


17 


21 


23 
25 
27 
31 
33 
35 


37 


FIRQB+FQFIL If the calling job is attached, this job must be detached. If the 
calling job is detached, this job must be attached. Both the calling 
job and this job must be running under the same PPN. 


Data Returned 


Other than a possible error in byte 0 of the FIRQB, the swap console function of 
the UU.ATT directive does not return any data. 
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Errors 


BADFUO The system returns this error for one of the following reasons: 
e Both the calling joh and the job specified at FIRQB+FQFIL are de- 
tached, or neither job is detached. 
e The job specified at FIRQB+FQFIL has a PPN different from the 


caller’s. 


e The value at FIRQB+FQSIZM is neither 0 nor 1. 
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3.36.5 UU.BCK (Change File Statistics) 
Privileges Required 
DATES is required to change the last access date. 


Data Passed 


FIRQB 
Mine- Octal Octal Mne- 
monic Offset Offset monic 


1 PEELALATALEL ULLAL PEA 0 


VIELE bE ED 


| channel no. (1-17) | 


2 


FQFUN 3 | —_-UU.BCK (= -13) 


FQSIZM5 


| _SB of last access 4 FQFIL 


7 MSB of last access 6 FQPPN 


| LSB of creation date 


11 : LSB of creation time | MSB of creation date 10 FONAMi1 


13 (//1/11i11 | MSB of creation time | 12 


15 | Pecan ey rer eere eae ay | 14 


17 | LEEI LIAISE T | 16 


21 E PAPTATOTIT AAA TALIS | 20 


PEAPALEACITAT ES TET LT AY | 22 


23 | 


25 | PALL ALET PEAT REA LG ES 24 


a7 | CPUMELALITA TEEPE LIE Fd | 26 


31 PAAAAT HET LA EEA LAT PAT 30 


33 | EL PALALE ET CPIE LAL ST ATA | 32 


35 | LLLTD EATEN TITEL A | 34 


37 | LI ALI EEE EEL ITEP EEL LY | 36 


FIRQB+5,6 The system internal format for dates has the form: 
FIRQB+7,10 [(year - 1970) * 1000] + day-within-year 


FIRQB+11,12 Time is specified in minutes until midnight, where 1440 equals 
midnight. 


NOTE 


See the .DATE directive for a discussion of these formats. 


Data Returned 


Other than a possible error in byte 0 of the FIRQB, the UU.BCK subfunction does 
not return any meaningful data. 


Errors 


BADFUO The file open on the channel specified is either not a disk file or is a user file 
directory (UFD). 


PRVIOL The disk is write protected or you do not have write access to the file. 


3-266 .UUO—UU.BCK 


3.36.6 UU.BYE (Logout) 


Privileges Required 
EXQTA is required to log out without a quota check. WACNT is required to log 


out without a 


Data Passed 


self-kill. 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
| . 
FQFUN 3 | UU.BYE(=5) | EULTLALL EY 2 
FIRQB+FQFIL Bits 0 and 1 specify: 
Bit Setting Meaning 
0 Clear Close I/O channels, deassign devices, remove re- 


ceivers, and dismount disks mounted /NOSHARE 


before performing logout. 


Set Perform logout only; do not close channels, 
deassign devices, remove receivers, or dismount 
disks. This call requires WACNT privilege. 


1 Clear Check quotas on all mounted disks before per- 


forming logout. 


Set Perform logout without checking disk quotas. 
This call requires EXQTA privilege. 


If the caller does not have WACNT privilege, RSTS/E forces Bit 0 
clear. If the caller does not have EXQTA privilege, RSTS/E forces 


Bit 1 clear. Bits 2 through 7 are reserved. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mnhne- 
monic Offset Offset monic 


| . 
enn | 
11 : | LILA PITTI 1 10 


27 LSB of current disk usage (in blocks) FQPFLG 


31 disk name (2 ASCII characters) 30 FQDEV 


33 | <>0, unit no. real _| disk unit number 32 FQDEVN 
35 | LIFTAPIAT IAT EL EST IAT aa 34 
37 ELDLAAAPALAG TE LAL AEL LY 36 


FIRQB+FQFIL Zero means neither disk quota nor detached job quota is exceeded. 
If you have WACNT privilege, the system returns control to your 
program. Otherwise, the system kills your job after performing 
necessary clean-up functions. Minus one means a quota is ex- 
ceeded; your job is still logged in. Minus two means a quota is 
exceeded, but your job is logged out. If you have WACNT priv- 
ilege, the system returns control to your program. Otherwise, 
the system kills your job after performing necessary clean-up 
functions. 


FIRQB+FQSIZ Indicates which quota is exceeded. (This value is valid only if 
FIRQB+FQFIL equals -1 or -2.) Zero means disk quota. One 
means detached job quota. 


FIRQB+FQMODE Returned if detached job quota is exceeded. FIRQB+FQMODE 
contains the number of detached jobs in the current account. 
FIRQB+FQMODE+1 contains the number of detached jobs al- 


lowed. 


FIRQB+FQDEV Returned if disk quota is exceeded. 


Errors 
No errors are possible with the UU.BYE subfunction. 
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3.36.7 UU.CCL (Add/Delete CCL Command) 


Privileges Required 


INSTAL is required to add or delete a CCL command. 


Data Passed — Add 


FIRQB 
Mne- Octal _ Octal Mne- 
monic Offset Offset monic 
1 OO TE ens 0 
FQFUN 3 -UU.CCL (= -30) (HITTTITT 2 
FQSIZM 5 ap nieN: point, chars must = 0 for add 4 FQFIL 
11 file name in RAD50 format 10 FQONAM1 
of program to run 
13 (2 words) 12 
15 | file type in RAD50 format (1 word) 14. FQEXT 
17 CCL command one to nine characters 16 FQSIZ 
padded with NULs (ASCII code 000) 
21 to nine characters 20 
23 22. 
25 24 
FQPROT 27 (must be 0) 26 
31 device name (2 ASCII chars) must be disk 30 FQDEV 
33 <>0,unit number real 32 FQDEVN 
35 line number to start exceution 34 FQCLUS 
37 PVE TTATI APATITES 36 
FIRQB+FQSIZ The name you give to the CCL command you are defining; from 
one to nine characters, padded with nulls. 
Example 
MOVB #UU.CCL, FIRQB+FQFUN ; FUNCTION CODE ADD/DELETE CCL 
CLRB FIRQB+FQFIL ; ADD FUNCTION 
MOVB #2, FIRQB+FQSIZM ; ABBREV. POINT IN CHARACTERS 
MOV #195.*256.+1,FIRQBt+FQPPN; PPN [195,1] 
MOV #°RTES, FIRQB+FQNAM1 ; FILE NAME IS TEST.TSK 
MOV #°RT ,FIRQB+FQNAM1+2 ; 
MOV #°RTSK, FIRQB+FQEXT : 
MOV #"XR,F IRQB+FQSI4 ; COMMAND IS "XRUN" 
MOV #"UN, FIRQB+FQSTIZ+2 : 
CLR FTROB+FOSI2+4 ; PAD COMMAND WITH NULLS 
CLR FIRQOB+FQSI2+6 : 
CLR FIRQBt+FQSI2Z+10 ; HIGH BYTE MUST BE ZERO 
MOV #"SY,F IRQB+FQDEV ; DEVICE NAME IS SY 
CLRB FIRQB+FQDEVN ; UNIT O 
MOVB #-~1, FIRQB+FQDEVN+1 ; AND UNIT NUMBER IS REAL 
CLR FIRQB+FQCLUS ; PROGRAM STARTS AT LINE O 


- UUO 


CREATE THE CCL 
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Data Passed — Delete 


FIRQB 
Mne- Octal Octal’) Mne- 
monic Offset | Offset monic 
: 
17 CCL command one to nine characters | 16 FQSIZ 
padded with NULs (ASCII code 000) 
21 to nine characters 20 
23 22 
25 24 


Data Returned 
Except for a possible error in byte 0 of the FIRQB, the UU.CCL directive does not 


return any meaningful data. 


Errors 


BADNAM For add only. The CCL command either begins with a number or contains 
an otherwise unacceptable character. 


INUSE For add only. The CCL command is already defined. 
NODEVC For delete only. The CCL command does not exist. 
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3.36.8 UU.CFG (Set Device/System Default Characteristics) 
Privileges Required | 
HWCEFG is required to: 
e Declare a device as restricted or unrestricted 
e Set magnetic tape default density 


¢ Set line printer characteristics 


SWCFG is required to: 

e Set magnetic tape label defaults 

° Set power fail delay 

e Set date/time presentation formats 
e Set system flags 


e Set dynamic region limit 


SWCTL is required to set or return system Answerback. 
HWCTL is required to enable/disable a device. 
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Data Passed (Set DEVn: characteristics) 


Mne- Octal 
monic Offset 


1 


FQFUN 3 


FIRQB+FQPPN 


FIRQB+FQPPN+1 
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FIRQB 


EIAAASAPALA ILA PALL 


[enmniinn 
[erie 


device name (2 ASCII chars) not a disk 


EPID TAMA ATT TALULA DAL 


LETT TALIA AAI 
| UU.CFG (= 42) PIII TA | 
| subfunction code =0 | 


par. change flags 


device unit number 


Octal Mne- 
Offset monic 


0 


2 


4 FQFIL 


6 FQPPN 


10 


12 


14 

16 

20 

22 

24 

26 

30 FQDEV 
32 FQDEVN 


34 


36 


Parameter change flags: 


Bit Setting 

0 Clear 
Set 

1 Clear 
Set 


2 Clear 
Set 


Meaning 

No change in enable/disable status 

Use value in FIRQB+FQPPN+1 to change status 
No change in device ownership 


Use value in FIRQB+FQPPN+1 to change own- 
ership 


No change in modem control 


Use value in FIRQB+FQPPN+1 to change mo- 
dem control 


Ail combinations of the bit values are legal. 


If FIRQB+FQPPN is zero, then this byte should also be zero. If 
FIRQB+FQPPN is not zero, then the following values are used to 
alter device parameters: 


Bit Setting 

0 Clear 
Set 

1 Clear 
Set 

2 Clear 
Set. 


Meaning 

Enable device 

Disable device 

No privilege needed for device ownership 
DEVICE privilege needed for device ownership 
Put device under LOCAL control 

Put device under MODEM control 


Data Returned (Set DEVn: characteristics) 


Except for a possible error in byte 0 of the FIRQB, the system returns the 
following: 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
| EIT LARILAALEDPESL EA Fa 0 
3 ID PEAT AATI LI LAA TALL Ta 2 
5 TALE ETIAAL TAIT LAT AG Ta 4 


. 


LALEEL LE ALE ALTA LLL 


LT ALAL LAS DAL ETA. 


be 
[irene 


FIRQB+FQPPN Device status flags indicating: 
Bit Setting Meaning 


0 Clear Device is enabled and free 
Set Device is disabled or in use 
1 Clear Device ownership does not require privilege 
Set Device ownership requires HWCFG privilege 
2 Clear Device is in LOCAL mode 


Set Device is under MODEM control 

Note that Bit 2 is only valid if the device name passed in 
FIRQB+FQDEV is KB. 

FIRQB+FQPPN+1 Valid values are: 0—If bit 0 in FIRQB+FQPPN is clear. 3—The 
device was disabled by this call and can be enabled by this call. 
Any even integer—Job number * 2 of the current device owner. 
Any odd integer (other than 3)-The device was disabled by the 
monitor and cannot be enabled. 
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Errors (Set DEVn: characteristics) 


INUSE An attempt was made to disable a device that was in use by another user or 
one that had been previously disable. 


NOTAVL An attempt was made to enable a device which was not disabled through 
use of this call. 


PRVIOL An attempt was made to alter device characteristic of a disk unit. 


Data Passed (Set LPn: characteristics) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
: : 


23 _ ietee ee ee | 22 
31 device name (2 ASCII chars) must be "LP" |; 30 FQDEV 
35 Neeeeeei ei ae | 34 
37 Br, | 36 
FIRQB+FQPPN Default Page Width; zero indicates no change, nonzero indi- 
cates the new value for the default page width. 
FIRQB+FQPPN+1 Default Printer Form Length; zero indicates no change, a 


nonzero value is the new default printer form length. The 
maximum value is 377 octal. 
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FIRQB+FQNAM1 Set characteristics flag bits mask. Zero indicates no change. A 
nonzero value represents the flag bits to be set in the charac- 
teristics flag word. The bit positions currently in use are: 


Bit 0 Allow <BS> for backspace (LA180) 
Bit 1 Do not process <BS> as backspace 
Bit 2. Allow 8-bit characters (LNO1) 

Bit 3 Allow nonprinting characters 

Bit 4 No fill for <FF> 

Bit 5 Allow <EOT> 

Bit 6 No <CR> required before <LF>,<VT>,<FF> (LP11) 
Bit 7 Ignore <CR> if next is <LF> (LP11) 
Bit 8 No <TAB> expanded (LNO1) 

Bit 9 Reserved 

Bit 10 Reserved 

Bit 11 Allow lower case (LNO1) 


Note that a value of 3 (set both bits 0 and 1) is illegal. All 
other combinations are permitted. 


FIRQB+FQNAM1+2 Clear characteristics flag bits mask. Zero indicates no change. 
A nonzero value represents the combination of flag bits to be 
cleared. See the previous discussion for FIRQB+FQNAM1 for 


an explanation of the bit. meanings. 


FIRQB+FQEXT Change special character flag. Zero indicates no change. 
One indicates a change to the Lineprinter Special Character 
(LPTSPC). 

FIRQB+FQEXT+1 If FIRQB+FQEXT is equal to one, then this byte contains the 
new Lineprinter Special Character. 

FIRQB+FQDEV The device name in two ASCII characters; must be LP. 

FIRQB+FQDEVN The line printer unit number on which to perform the opera- 
tion. 
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Data Returned (Set LPn: characteristics) 


Except for a possible error in byte 0 of the FIRQB, the system returns the 
following: 


FIRQB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


ewig [arte ae 
aren opeal shee [17/11/7170 
[riven 


LAA LIGAPTALATESS LAAT 


6 FQPPN 


10 FQONAM1 


12 


14. FQEXT 


16 FQSIZ 


20 


22 


24 


ELELLEEAAAPATLT A OLED 26 


30 


32 


34 


36 


FIRQB+FQPPN Current width of the LP unit specified in FIRQB+FQDEV and 
FIRQB+FQDEVN. 


FIRQB+FQPPN+1 Current value of the case flag. 
FIRQB+FQNAM1 Current value of the characteristics flag word. 
FIRQB+FQEXT+1 Current value of the special character. 
FIRQB+FQSIZ Current value of the default form length. 


Errors (Set LPn: characteristics) 


BDNERR An attempt was made to set both bits 0 and 1 in the characteristics flag 
word. 


NODEVC An attempt was made to set characteristics of a printer which is not sup- 
ported by the monitor, or the device name specified in FIRQB+FQDEV was 
not LP. 
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Data Passed (Set System Defaults) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset | Offset monic 
1 | LTTE EIAALT LL PAE Ta | O 
FQFUN 3 | UU.CFG(=42) | PITILILTL | 2 
5{ ///ii/i/ii | subfunction code =2 | 4 FQFIL 
7 | powerfail delay in seconds ! 6 FQPPN 
11 | default time format | default date format 10 FQNAM1 
19 | = ///I///111 | defaulttapelabel =| 12 
15 | default tape density 14 FQEXT 
17 | dynamic region limit 16 FQSIZ 
21 PEELE CLEA AEE CATES TIA | 20 
23 PPLTIATAPIAT IAT TTI ALT | 22 
25 | CLALIT ATTA ITS | 24 
27 | PTLEITSTTATA ATA Aa | 26 
31 | LELTLAA LILLE LE AALT CE | 30 FQDEV 
33 | FELT AALELA FLEE EP LEE | 32 FQDEVN 
35 | ELLE AA ATET AAT PEL LE TY | 34 
37 | ST ITUITHATI OTE TT | 36 
FIRQB+FQPPN Default powerfail delay in seconds. Zero indicates no change. 
A nonzero value represents the new default powerfail delay. 
The maximum is 454 (octal) seconds. 
FIRQB+FQNAM1 Default date format. Zero indicates no change. One indicates 
NUMERIC date format. The ALPHA date format is indicated 
by 377. 
FIRQB+FQNAM1+1 Default time format. Zero indicates no change. One indicates 
24 hour time format. The 12 hour (AM/PM) time format is 
indicated by 377. 
FIRQB+FQNAM1+2 Default magnetic tape label. Zero indicates no change. One 
indicates DOS magnetic tape label. The ANSI magnetic tape 
label is indicated by 377. 
FIRQB+FQEXT Default magnetic tape density in bits per inch (bpi). 
FIRQB+FQSIZ Nonprivileged user dynamic region limit. Zero indicates no 


change, minus one (-1) sets the limit to 0 K words. A value 
between 1 and 2048 sets the limit to that value in K words. 
The sum of the dynamic region sizes owned by all nonprivi- 
leged users cannot exceed the limit value given here. If a user 
without INSTAL privilege attempts to create a region whose 
size, when added to all other nonprivleged region sizes, exceeds 
this limit, the system returns a NOROOM error message and 


does not create the region. 
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Data Returned (Set System Defaults) 


FIRQB 


Mne- Octal Octal 
monic Offset Offset 


default eee density 


eyneinic Poco nuit 


FEE TAEL TEES TIT TTIAADS 


eee, 


ETAT TTA 
TERT 


Mne- 
monic 


FQPPN 


FQNAM1 


FQEXT 
FQSIZ 


FIRQB+FQPPN The number of seconds to delay of powerfail restarts. 
FIRQB+FQNAM1 Default date format. One indicates NUMERIC date format. 

The ALPHA date format is indicated by 377. 
FIRQB+FQNAM1+1 Default time format. One indicates 24 hour time format. The 

12 hour (AM/PM) time format is indicated by 377. 
FIRQB+FQNAM1+2 Default magnetic tape label. One indicates DOS magnetic tape 

label. The ANSI magnetic tape label is indicated by 377. 
FIRQB+FQEXT Default magnetic tape density in bits per inch (bpi). 
FIRQB+FQSIZ Default region limit in K words. 


Errors (Set System Defaults) 


FIXERR 
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An attempt was made to specify a powerfail delay value greater than 454 


(octal) seconds. 


Data Passed (Load and Remove Monitor Overlay Code) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, 7 
FIRQB+FQPPN Operation flag. Zero indicates load the named overlay code. A one 
indicates unload the named code. 
FIRQB+FQNAM1 Internal overlay name in RAD50 format. These names are subject 


to change in future releases of RSTS/E. Presently, the following 
names have been defined: 


DIR Handles directory lookups 
DLN Handles delete and rename 
LIN Handles the UU.ATR SYS() call 


PFB Handles several functions used by the DCL command file 
processor 


TRM Handles the set-terminal-characteristics (UU.TRM) SYS() 
call. 


UUO Handles UU.TB1, UU.TB2, UU.TB3, UU.FCB, UU.CNV, 
UU.SYS, and UU.ERR 


FUT Handles UU.FIL SYS() call 
Data Returned (Load and Remove Monitor Overlay Code) 


Except for a possible error in byte 0 of the FIRQB, for a load operation, the 
system returns the amount of XBUF used (in bytes) in FIRQB+FQPPN. The 
remove monitor overlay code operation does not return any data. 
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Errors (Load and Remove Monitor Overlay Code) 


INUSE The overlay code specified is already loaded. (Load) 

NOBUFS There is not enough XBUF available to load the named overlay code. (Load) 
NODEVC The named overlay code is not loadable. (Load) 

NOSUCH The overlay name is invalid. (either) 

NOTMNT The overlay name is not loaded. (Remove) 


Data Passed (Set and Return System Answerback Message) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
Fasizms rng 4 FOFIL 
7 | | 6 FQPPN 

11 10 

13 12 

15 | 14 

17 | Answerback 16 

21 Message 20 

23 Text 22 

25 24 

27 26 

31 30 

33 32 

35 | 34 

37 36 

FIRQB+FQSIZM Flag= -1 to return the Answerback text 
Flag > 0 to set the Answerback text. 
FIRQB+FQPPN The ASCH string for the Answerback text. 
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Data Returned 


Mne- Octal 
monic Offset 


21 
23 
25 
o/s 
31 
33 | 
35 
37 
FIRQB+FQPPN 
Errors 
PRVIOL 
NOTAVL 
NOBUFS 


IIIA TIITIETI TTT I TT I 
LIELIIEITITT IIIT ITT TT | 2 
LISP ITEITT subfunction code =7 | 


FIRQB 
Octal Mne- 
Offset monic 


0 


4 FQFIL 


6 FQPPN 


10 


Answerback 


Message 


Text 


Answerback message text returned if Flag = -1. 


Current user does not have the SWCTL privilege. 
There is no Answerback text to return. 
There are no buffers available to store the text. 
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3.36.9 UU.CHE (Enable/Disable Disk Caching) 


Privileges Required 


TUNE is required to enable or disable disk caching. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LAAT TT TP TIAAT TEE 
| UU.CHE. (= 23) APTI TITTT 


1 


FQFUN 3 
FQSIZM5 4 FQFIL 
7 6 FQPPN 


11 | 10 FQNAM1 


Denn 
[inn 
enn 


FIRQB+FQSIZM The number of blocks used in a caching operation. 
FIRQB+FQFIL 0 Enable directory and data caching 
1 Disable all caching 


13 


15 14 FQEXT 
17 
21 
23 
25 
27 


31 


33 
35 


37 


200 Return current caching parameters 
FIRQB+FQEXT O Use current setting 
1 Enable caching as specified in file open mode or UFD setting 


100 Cache all data transfers regardless of the file open mode or 
VED setting 


200 Disable all caching 
FIRQB+FQEXT+1 O Use current setting 
1 Allow use of small buffer pool (ignored) 
200 Do not use small buffer pool 


FIRQB+FQSIZ The new value of the cache replacement time, in seconds. Specify 
zero for no change. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


| PELL ALTAATA LA TAL EE LY 
| FATA PETER TAPIA TAAL | : 
cache cluster size current cache setting 


limit on total number of cache clusters 


1 


3 


FQSIZM5 


4 FQEFIL 


7 6 FQPPN 


11 limit on clusters for directory caching | 10 FQNAM1 


limit on sietaie for user data caching 

doutrals aa. buffers | 
-renternet 
ee 
amber fants 


number of invalid tags | 30 FQDEV 


13 


15 14 FQEXT 


17 16 FQSIZ 


21 20 FQNAM2 


23 22 FQMODE 


25 24 FQFLAG 


27 26 FQPFLG 


31 


33 | 


LLEL ELE CAPE LAL SL Ll 
35 | ED IALES LALAAT ATLL A LAY 


| CEDALALLELAPELAT AEE ELL : 


FIRQB+FQFIL Current cache settings and available options: 
0 All caching disabled. 


1 Directory caching enabled, data caching is disabled. 


37 


200 Directory caching disabled, data caching is enabled. 
201 Directory caching enabled, data caching is enabled. 
FIRQB+FQSIZ The time in seconds that an unused cache can be kept in memory. 


FIRQB+FQNAM2 The amount of small buffers used for caching (in units of cache 
clusters). Always zero. 


FIRQB+FQMODE The amount of XBUF used for caching (in units of cache clusters). 


FIRQB+FQFLAG The number of cache clusters in XBUF used for directory caching. 
FIRQB+FQPFLG The number of cache clusters in XBUF used for data caching. 
FIRQB+FQDEV The number of invalid cache clusters in XBUF. 

Errors 

INUSE All of the clusters allotted to the cache are in use. 


NOROOM Not enough XBUF space to enable data caching. System manager must 
allocate at least 3K words. 


NOTAVL Tried to change cluster size while cached file disk transfer in progress; retry. 
PRVIOL Current user does not have TUNE privilege. 
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3.36.10 UU.CHK (Check File Access/Privilege Name/Privilege Mask Handling) 


The UU.CHK directive performs a variety of privilege checking functions. It 
takes a subfunction code in FQFIL. The subfunction codes are: 


0 Check file access rights. You can use this subfunction to check access rights to a 
file of known protection code and PPN without performing the OPEN function. If 
a file’s access rights need to be checked but the protection code is not known, the 
most straightforward method is to open the file. You can also use this subfunction to 
define file-like access rules for objects other than files. For example, the Print/Batch 
Services programs use this subfunction to control access to jobs. 


1 Convert privilege name to mask. You can use this subfunction to convert a privilege 
name to its internal representation or to determine whether a user has a specific 
privilege. 

2 Convert privilege mask to name. You can use this subfunction to generate the 


symbolic form of a privilege mask. It scans the specified privilege mask looking for 
a bit that is set. If none are found, the error NOSUCH is returned. Otherwise, the 
first one found is cleared and the privilege name is returned in FIRQB+FQNAM2. 


Privileges Required 


None 


Data Passed - Check File Access Rights 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
(iin) 
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Data Returned - Check File Access Rights 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[rennin 


FIRQB+FQERNO The bits are set to indicate access rights as follows: 
Bit O Owner rights are granted 


4 FQERNO 


Bit 1 Read access is not allowed 
Bit 2 Write access is not allowed 
Bit 5 Execute access is not allowed 


Bit 6 Accounting rights are granted or the PPN is the same 
as that of the caller. 


Bit 7 Accounting rights are granted 
Bits 3, 4, and 8 to 15 are reserved for use by Digital. 


Errors 
No errors are possible with this subfunction of UU.CHK. 
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Data Passed - Convert Privilege Name to Mask 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
11 privilege name as a escheracler _ 10 FQNAM1 
13 | uppercase ASCII string or "ALL" 12 
15 padded with NULLs | 14 
23 | | PAATUET AI AD EAT Ed | 22 
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Data Returned - Convert Privilege Name to Mask 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


a 


privilege mask 


0 
2 
4 FQERNO 
6 
10 FQNAM1 
| 12 
(4 words) 
14 


16 


20 


[eon 


FIRQB+FQERNO If the passed privilege name was not ALL: 


Zero means the current job has the named privilege. 


22 
24 
26 
30 
32 
34 


36 


One means the current job does not. 
If ALL was passed: 
Zero means the current job has all privileges. 


One means the current job does not. 


FIRQB+FQNAM1 If the passed privilege name was not ALL, the bit corresponding 
to the named privilege is set. All other bits are clear. 


If ALL was passed, all privilege bits that currently have meaning 
are set. All other bits are clear. 


Errors 


NOSUCH The name passed in FIRQB+FQNAM1 is not a valid privilege name. 
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Data Passed - Convert Privilege Mask to Name 


FIRQB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


} 12 


1 0 


FQFUN 3 2 


4 FQFIL 


6 


10 FQNAM1 


privilege mask 


(4 words) 14 


16 


20 


22 


24 


26 


30 


32 


34 


36 
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Data Returned - Convert Privilege Mask to Name 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[mmm —_] 
rr —_| + 
irri | + 
renin] ° 


10 FQNAM1 
privilege mask | 12 

(4 words) 14 
16 


20 FQNAM2 


6-character uppercase ASCII string 


22 
padded with NULLs 
24 


inn | 
rinse | 
rin | 
rine | 
Cine | 


FIRQB+FQNAM1 The privilege mask is the same as that passed except that any 
undefined bits and the bit corresponding to the name in FQNAM2 
is turned off. As a result, a subsequent call using the returned 

~ mask would return the name of the next privilege. This makes it 
easy to translate an entire mask by repeated calls to this function. 


FIRQB+FQNAM2 The name of the privilege corresponding to the first set bit in the 
mask. 7 


Errors 


NOSUCH The privilege mask in FIRQB+FQNAM1 is zero or specifies only unassigned 
privilege bits. 
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3.36.11 UU.CHU (Set Password, Change Password/Quota/Expiration Date, 
Disable Terminal,Kill Job) 
This directive has five subfunctions: 
e Set Long Password 
e Change Quotas (updated format), Expiration Date, and Short Password 
e Change Quotas (pre-V9.0 format), Expiration Date, and Short Password 
e Disable Terminal 


e Kill Job 


Privileges Required (Set Long Password) 
GACNT or WACNT are required to set passwords. 


Data Passed (Set Long Password) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[am 


1 0 


FQFUN 3 2 


4 FQEFIL 


6 FQPPN 


10 FQNAMI1 
12 
| 14 


long password 16 


(14 bytes, padded with NULLs) 20 


22 


24 


26 


mim | 
(must be 877) 


PEIALALAIVLT TE EAL EL 


30 


32 


34 FQCLUS 


36 


FIRQB+FQNAM1 If the first byte is zero, the password information is deleted (this 
turns the account into a nonuser account). If password lookup 
is enabled using CREATE/ACCOUNT or SET PASSWORD then 
the password must consist of six uppercase letters or numbers. 
Otherwise, it can contain any character except the question mark 
(?). The monitor also enforces a minimum password length of six 
characters. 
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NOTE 


In this subfunction, the PPN is specified in a different place than in 
the "Change Short Password/Quota" subfunctions where the PPN is 
specified in FQNAM1. 


Privileges Required (Change Short Password, Quotas V9.0 & Higher, or 
Expiration Date) 


GACNT or WACNT are required to set passwords, quotas, or expiration date. 


Data Passed (Change Short Password, Quotas for V9.0 & Higher, or Expiration 
Date) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 PRE EED APL AA LAL PEE EEL 0 
FQFUN 3 UU.CHU (=10) ageneaye 2 
5 flag byte detached job quota | 4 FQFIL 
7 TEED PTALT AE EL LULL ed 6 
13 new password in RADS50 format |} 12 
(2 words) 
15 (zero if no change) 14 
17 logged-out quota (LSB) 16 FQSIZ 
23 logged-in quota (LSB) 22 FQMODE 
25 |logged-out quota(MSB) logged-in quota(MSB) 24 FQFLAG 
31 device name (2 ASCII characters) 30 FQDEV 
37 VELERADIT EELEL TMM CTE | 36 
FIRQB+FQFIL The number of detached jobs allowed under this account. 
FIRQB+FQFIL+1 Flag byte. Zero means change the disk quotas using the pre-V9.0 
format (see the next subfunction). Nonzero means the following: 
Bit 0 Change logged-out quota 
Bit 1 Change logged-in quota 
Bit 2 Reserved 
Bit 3. Change detached job quota 
Bit 4 Reserved 
Bit 5 Reserved 
Bit 6 Reserved 
Bit 7 Change disk quotas using updated format 
FIRQB+FQSIZ The LSB of the logged-out quota. 
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FIRQB+FQBUFL Zero means no change. Nonzero means this value is the new 
expiration date. 


FIRQB+FQMODE The LSB of the logged-in quota. 


FIRQB+FQFLAG The MSB of the logged-in quota. 

FIRQB+FQFLAG+1 The MSB of the logged-out quota. 

FIRQB+FQPFLG To change disk quota, set this byte to 377. 
FIRQB+FQDEV The device name as two ASCII characters. 
FIRQB+FQDEVN The device unit number, passed as a binary value in byte 


FIRQB+FQDEVN. A nonzero value in FIRQB+FQDEVN+1 
indicates an explicit device unit number. A zero value in 


FIRQB+FQDEVN+1 indicates no device unit number. 


Privileges Required (Change Short Password, Pre-V9.0 Quotas or Expiration 
Date) 


GACNT or WACNT are required to set passwords, quotas, or expiration date. 


Data Passed (Change Short Password, Pre-V9.0 Quotas or Expiration Date) 


~FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


VALAAPE EEL LAAT LATA T 


1 


FQFUN 3 


10 FQNAM1 
13 new password in RADS50 format 12 


(2 words) 
(zero if no change) 


RTE 
[5a war wumber eat [ doc nt ro 


Segeeeetoreek aga s aa) 


FIRQB+FQBUFL Zero means no change. Nonzero means this value is the new 
expiration date. 


FIRQB+FQPFLG To change disk quota, set this byte to 377. 
FIRQB+FQDEV The device name as two ASCII characters. 


16 FQSIZ 
20 FQBUFL 


26 FQPFLG 


30 FQDEV 


32 FQDEVN 


34 FQCLUS 
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FIRQB+FQDEVN The device unit number, passed as a binary value in byte 
FIRQB+FQDEVN. A nonzero value in FIRQB+FQDEVN+1 
indicates an explicit device unit number. A zero value in 
FIRQB+FQDEVN+1 indicates no device unit number. 


Privileges Required (Disable Terminal) 
HWCTL is required to disable a terminal. 


Data Passed (Disable Terminal) 


FIRQB 
Mne- Octal 
monic Offset 


1 


FQFUN 3 


Privileges Required (Kill Job) 
JOBCTL is required to kill a job. 


: LEGILLALALDEETUALE AES | 
UU.CHU (=10) EIREET AT 
| LEE Toh | keyboard number — | 


(must = 377) | (must = 377 
|! PIPATT TAT TIT A LACT IA | 


Octal 


Mne- 


Offset monic 


FQFIL 


FQCLUS 
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Data Passed (Kill Job) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


Peres eee ee ee sees 


1 | a 0 

5 - job number to kill, 4 FQFIL 

11] Pari ee | to 

vend. | TTT TTT | 14 

27 a “PEPE ETAT ATTA i | 26 

31 . TTT | 30 
FIRQB+FQFIL Specify zero to kill current job. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.CHU subfunction does 
not return any meaningful data. 


Errors 


BADFUO The system returns this error for one of the following: 


e Change password/quota. Device specified is not a disk. 
¢ Kill job. Job number is out of range or the job does not exist. 
e Disable terminal. The keyboard number is: 

— Greater than number of keyboards on system 

— A pseudo keyboard 

— Currently opened or allocated by a job 


BADNAM For change password/quota. Password is too short, or too long, or contains 
illegal characters. 


NOSUCH For change password/quota. Account not present on disk specified. 
NODEVC For change password/quota. Device specified is not on the system. 
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3.36.12 UU.CNV (Date and Time Conversion) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, . 
5 | internal fora date (see DATE):0 = saent | 4 FQFIL 
17 | PETTLALLTTTALLLLTTAA 16 
FIRQB+FQFIL The date to be converted, or zero for the current date. 
FIRQB+FQPPN Zero means use system default format. A value less than zero 
means use alphabetic date format. A value greater than zero 
means use ISO numeric date format. 
FIRQB+FQMODE The time to be converted, or zero for the current time. 
FIRQB+FQFLAG Zero means use system default format. A value less than zero 


means use 12-hour time format. A value greater than zero means 
use 24-hour time format. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


CELE EE TA OLS 


1 0 
5 (same as data posse) 4 FQFIL 
7 (same as data ss assnays 6 FQPPN 
11 | 10 FQNAM1 
13 date string (padded 12 
15 | at end with NULLs) 14 
17 dd-mmm-yy or yy.mm.dd 16 
21 20 
25 Gagné as data passed) 24 FQFLAG 
27 26 FQPFLG 
time string (padded 
31 30 
| at end with NULLs) 
33 32 
hh:mm xm or hh:imm 
35 34 
37 EPAPL AL ALIA ALE ELL EY 36 


Errors 


No errors are possible; however, if the date or time passed is illegal, random 
output is generated. 
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3.36.13 UU.DAL (Deallocate All Devices and Deassign All User Logicals) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
FIRQB+FQFUN The function code UU.DAL (octal value equals 14) 
FIRQB+FQFIL The deassign-only flag. Must be zero. 


Data Returned 
The UU.DAL subfunction does not return any data. 


Errors 
No errors are possible with the UU.DAL subfunction. 
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3.36.14 UU.DAT (Change System Date/Time) 


Privileges Required 


DATES is required to change system date or time. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
FOFUN 3 | UU.DAT (=-16) | poteiee?, 2 
21 | RL a | 20 
ws [_errininininie—) 
FIRQB+FQFIL The system internal format for date is: 
[(year - 1970) * 1000] + day-within-year 
FIRQB+FQPPN Time is expressed as minutes until midnight, where 1440 equals 


midnight. 


NOTE 


A value of zero in either of these fields means no change is to be made. 
See the .DATE directive for a discussion of these formats. 


Data Returned 
The UU.DAT subfunction does not return any data. 


Errors 


PRVIOL Dates prior to 1-Jan-90 cannot be set. 
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3.36.15 UU.DEA (Deallocate Device) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. 
: ; 
31 device name (2 ASCII characters) or 0 30 FQDEV 
35 PELTPEVEALTL EAT FATES | 34 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.DEA subfunction does 
not return any meaningful data. 


Errors 


NODEVC The device or device type in the two words at FIRQB+FQDEV is not on 
the system. 
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3.36.16 UU.DET (Detach) 


Privileges Required 


None required to detach the caller’s job (depending on quotas). JOBCTL is 
required to detach another job. EXQTA is required to suppress the detached job 
quota check. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LITT TTP | 
UU.DET (= 7) PATTI | 


PEITALT AT j close flag & job no. | 


PETTITT EA Le 
! PET PTT II ESP 
LIT PLET PITT PP ELLIOT EL 


. LILIIIITTTETTT TTT TTT AT 


1 


FQFUN 3 


5 


7 


11 


13 


15 


17 


21 


DALAL TAPE LALA EAVES 


ERT AHA AALADL ELE DATA LD 


23 


25 
a7 
31 


33 


| FPITATTI IIL PL 
PAITIT PIT AT ETA 


VIDATAL ELE TATA CEL ATA 


FIRQB+FQFIL Flag byte as follows: Bits 0-6 equals the job number to detach. If 
zero, detach calling job. Bit 7 clear means do not close terminal 
channels or deallocate terminal. Bit 7 set means close all channels 
on which terminal is open and deallocate terminal, if allocated. 


35 


37 


NOTE 


If a job running under control of an indirect command file is detached 
using the UU.DET directive, a new job is created at that terminal, 
logged in to the same account, and execution of the command file 
continues with the new job. The detached job retains its job number, 
while the command file resumes under a different job number. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.DET subfunction does 
not return any meaningful data. 
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Errors 


BADFUO The current job is already detached. 
QUOTA The detached job quota for the account has been reached. 
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3.36.17 UU.DIE (System Shutdown) 


Privileges Required 


SHUTUP privilege is required to shut down the system. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | PALTA TIAA IATA L TTT TTY | O 
FQFUN 3 | UU.DIE (= -20) L774 2 


: Flag word 4 FQFIL 
TIPLE PAAPAITL TPT 
LAA ALAA LT IPA TALE ALS 


5 
7 
11 


13 


ELIT ATIALAE TERT AT SL YT Sf 
| CLEA EIATALLTATTA PTL AA 


15 


17 


LAV AAV APL ATIATS LET TI 
TLALPAPALAL IA PATI AA Ea 


t 


21 | 
23 


TEEAEELLE ELE EEE PEALE ELS 
CLL ELTA ELAII AS PATEL 


25 


27 


LEE EA PATTI AA ETAL EE 


31 


CALLED D EL EALAL ATE LE A 


33 


FAVALATALL IAA THIA LIA LS 


Ses poe ee eeeore ea sae a: 


35 


PPELEVITTALET LT I PELE ES 


37 


FIRQB+FQPPN Flag word = 0 means no automatic restart (stop in INIT.SYS). 


Flag word = 1 means automatic restart. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.DIE subfunction does 
not return any meaningful data. 


Errors 


BADFUO One of these conditions has not been met: 


e Only one job can be running 

e Logins must be disabled 

e No disks except the system disk can be mounted 
e No files can be open on the system disk 


3-302 .UUO—UU.DIE 


3.36.18 UU.DIR (Directory Lookup) 


Privileges Required 


If the device is restricted, DEVICE privilege is required to perform directory or 
disk lookup on the caller’s account. File read or execute access (by protection 
code, GACNT or WACNT privileges) is required to perform disk directory lookup 
on another account. 


Data Passed — Directory Lookup on Index 


FIRQB 

Mne- Octal Octal Mne- 
monic Offset Offset monic 

7 aon ceemeee ee ( | ae He 

13 12 

15 14 

17 16 

21 20 

23 22 FQMODE 

25 24 

27 26 

31 30 FQDEV 


FIRQB+FQFIL The index for the file to read. If the index is zero, UU.DIR returns 
the data for the first file in the directory. If the index is n, UU.DIR 
returns the the data for the n+/th file in the directory. 

On magnetic tape, the index must be zero to rewind the tape 
before reading the first file. On DECtape, the index must be 
zero to read the directory blocks from the tape before reading the 


first file. Subsequent calls, where the index is not zero, read the 
directory from the BUFE‘SYS file. 


FIRQB+FQPPN Specifies the PPN to look up. For disks, the PPN defaults to 
the caller’s PPN. For DOS format magnetic tape; a zero in 
FIRQB+FQPPN means look up files regardless of PPN, a nonzero 
means only files with that PPN are returned. For ANSI magnetic 
tape and DECtape, RSTS/E ignores FIRQB+FQPPN. 


FIRQB+FQMODE Marked-for-delete flag. Bit 14 set causes UU.DIR to return infor- 
mation about marked-for-delete files. 
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Data Returned — Directory Lookup on Index 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


PATTI IATA TAT AT a eed 


(same as data passed) 
project number programmer number 


file name in RAD50 format 
(2 words) 


[settee 
MSB of file size 


| 24 FQFLAG 


2 FQJOB 
4 FQFIL 
6 FQPPN 


10 FQNAM1 


14 FQEXT 
16 FQSIZ 
20 FQNAM2 


22 FQMODE 


date of creation 


(same as data passed) | 


(same as data passed) 


file cluster size 


FIRQB+FQMODE System internal format for date is: 
FIRQB+FQFLAG [(year - 1970) * 1000] + day-within-year 
FIRQB+FQPFLG Time is returned as minutes before midnight, where 1440 equals 


midnight. For look up on DOS format magnetic tape, this field 
contains the PPN of the file. 


26 FQPFLG 
30 FQDEV 
32 FQDEVN 


34 FQCLUS 
36 FQNENT 


NOTE 


See the .DATE directive for a discussion of the date and time formats. 


FIRQB+FQNENT+1 The USTAT byte from the UFD Name entry. This byte contains 
the following internal flag information (for disk only): 


Bit Meaning When Set 

File is placed 

Some job has write access now 

File is open in update mode 

File is contiguous; no extend allowed 
No delete or rename allowed 


File is marked for deletion 


JI Oo £® WO DN & 
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Errors 


BADDIR The directory structure is invalid. For magnetic tape, this error usually 
indicates you are reading an ANSI format tape in DOS mode, or a DOS 
format tape in ANSI mode. 


DEVNFS The device specified is non-file-structured. 


NOSUCH The account specified does not exist on the device or no more files exist on 
the account. 


xxxxxx The call also returns device-dependent errors such as NOTMNT (disk pack 
not mounted). | 


Data Passed — Special Magnetic Tape Directory Lookup 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
{in de 
33 |<>0, unit number real 32 FQDEVN 
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Data Returned — Special Magnetic Tape Directory Lookup 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


SS 2000077777171 
i Rea | | current job no." 2 | 


file name in RAD50 format 
(2 words) 


file type in RAD50 format (1 word) 
! EEYE LILI TTL SE EPL ETAT 
PELTTI EA ES protection code | 


2 FQJOB 


4 FQFIL 


6 FQPPN 


10 FQNAM1 


14. FQEXT 


20 FQNAM2 


| ~ date of creation 


r : 
| 


22 FQMODE 


LETITA TL TALIA ELAS ET 


project number | programmer number _| 
| (same asdata passed) i as data pag seal | 
| (same asdatapassed) a Aas as data maeeed) | | | 

rin 


FIRQB+FQMODE System internal format for date is: 
[(year - 1970) * 1000] + day-within-year 


FIRQB+FQNENT The number of entries returned: for disk, eight; for tape, six. (Not 
returned for SYS 17.) 


25 


FQPROT 27 26 FQPFLG 


31 30 FQDEV 


33 32 FQDEVN 


35 


37 36 FQONENT 


Errors 


BADDIR This error usually indicates you are reading an ANSI format tape in DOS 
mode, or a DOS format tape in ANSI mode. 


NOSUCH No more files exist on the tape. 
DEVNES The device specified in the two words at FIRQB+FQDEVN is either non-file- 


structured or not a magnetic tape. 
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3.36.19 UU.DLU (Delete User Account) 


Privileges Required 
GACNT or WACNT is required to delete a user account. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
: 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.DLU subfunction does 
not return any meaningful data. 


Errors 


DEVNES Device is not disk or is a disk open in non-file-structured mode. 
PIEXST The account contains files. 

INUSE A user is currently logged in to the system under the account. 
NOSUCH The specified account does not exist. 

PRVIOL Account specified is either [0,0] or [0,1]. 


Discussion 


U.DLU deletes a user account from a private disk or the public structure. If 
the error ?Device not available (ERR=8) occurs, you must first delete all files in 
the account and release the UFD clusters with UU.ZER or the DCL DELETE 
command. 
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3.36.20 UU.DMP (Snap Shot Dump) 


Privileges Required 
SYSIO is required to perform a snap shot dump. 


Data Passed 
FIRQB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


1] PULP LITT TAT ATT TET 0 
FQFUN 3 |  UU.DMP(=-33) | 9 /////////1 2 


VILPETAI ATE TA Taal 


REA TALILALAA TAL TA TA 


ALA LT POLE TITLE LT LLG Ll 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.DMP subfunction of 
.UUO does not return any meaningful data. 


Errors 


BADFUO A user without SYSIO privilege attempted to execute this call. 


NOSUCH The call tried to write data to the file CRASH.SYS, but crash dump was 
not enabled. This error occurs if RSTS/E tries to allocate a crash dump file 
during system start-up but could not due to lack of disk space. 


XXXXKX The call also returns device-dependent errors such as HNGDEV or 
NOTMNT. 


Discussion 


UU.DMP writes the current monitor image executing in memory and the contents 
of the extended buffer pool (XBUF) to the crash dump file [0,1JCRASH.SYS. 
XBUF contains monitor data structures, including DECnet/E data structures and 
caching information. You can analyze the contents of the CRASH.SYS file with 
the ANALYS program (see the RSTS/E System Manager’s Guide). 
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3.36.21 


UU.ERR (Return Error Messages) 


Privileges Required 


None 


Data Passed 


FIRQB 


Mne- Octal Octal 


monic Offset 


1 
FQFUN 3 
5 
7 
11 
13 
15 
17 
21 
23 
25 
27 
31 
33 
35 


37 


. 
: 
Pri | wwornonoer | 4 
: 
: 
? 
: 
: 
: 
: 
: 
: 
: 
s 
; 


Mne- 


Offset monic 


FQERNO 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 LITTITISITIT TTT TTT I 0 


FQFUN 3 |KB*2;1’s comp=detach 2 FQJOB 


5 | 4 FQERNO 

7 6 
11 10 
13 error message - padded with NULLs 12 
15 to 28. characters (ASCII format) 14 
17 | 16 
21 20 
23 22 
25 24 
27 26 
31 30 
33 32 
35 34 
37 36 


Errors 
No errors are possible with the UU.ERR subfunction. 


Discussion 


UU.ERR extracts error message text from the error message file installed during 
the current time-sharing session or from the default error message file if an error 
message file is not currently installed. The text is associated with the value 

of the ERR variable passed at FIRQB+FQERNO (usually FIRQB+FQFIL). The 
number in FIRQB+FQFUN of the returned string is two times the number of the 
keyboard on which the job is running. 
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3.36.22 UU.FCB (Get Open Channel Statistics: WCB/DDB/FCB) 


The WCB is the Window Control Block for the file system. The DDB is the Device 
Data Block for nondisk devices. The FCB is the File Control Block for the file 
system. Note that the WCB, DDB, and FCB are internal RSTS/E structures that 
are subject to change at any time. 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 PIIIITEPTITT STATI TTT TT | 


FQFUN 3 UU.FCB (= -10) 


7 
11 
13 
15 
17 
21 
23 
25 
27 
31 
33 
35 | 


37 bl ELEELTAAL UD EEE EE 


FIRQB+FQSIZM Zero returns WCB or DDB information. One returns FCB infor- 


mation. 


.UUO—UU.FCB 3-311 


Data Returned (for subcode = 0) 
For DDB or WCB. 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
: . 
27 word 10 of either the NEE or DDB 26 FQPFLG 
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Data Returned (for subcode = 1) 


For FCB. 


Mne- Octal 
monic Offset 


1 
3 
FQSIZM5 


7 


FIRQB 
Octal Mne- 
Offset monic 


FQJOB 
FQFIL 


11 LSB of file size FQNAMI1 
13 PPN of file 


15 


| FQEXT 
name of file 
17 FQSIZ 


2 
: 
: 
: 
: 


FIRQB+FQFIL 


FIRQB+FQSIZM 
FIRQB+FQPPN 


The number of user who have a file open in a mode other than 


read regardless. 


The number of user who have a file open in read regardless mode. 


This byte contains the following internal flag information: 
Bit Meaning When Set 


Placed file 

Some job has write access now 

File is open in update mode 

File is contiguous; no extend allowed 
No delete or rename allowed 

File is a UFD 


File is marked for deletion 


NID 7 FF OO NY & 
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Errors 


BADFUO 


BSERR 


NODEVC 


NOTOPN 


Discussion 


The subfunction code passed in FIRQB+FQSIZM is a value other than zero 


or one. 


The channel number specified at FIRQB+FQFIL is outside the range 0 
through 17. 


You requested FCB information (FIRQB+FQSIZME=1), but the file open on 
the I/O channel specified at FIRQB+FQFIL is not a disk file. 


The I/O channel specified at FIRQB+FQFIL is not open. 


UU.FCB returns information kept in the DDB, WCB or FCB data structures. 
Note that these data structures are internal to RSTS/E and subject to change at 


any time. 


Specifying 0 in FIRQB+FQSIZM returns information kept in the DDB or WCB 
data structures. 


Specifying 1 in FIRQB+FQSIZM returns information kept in the FCB, including 
open counts, status byte, and current file size. RMS uses this call to determine 
file characteristics. 
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3.36.23 UU.FIL (File Placement and Modification) 


Privileges Required 


Read access (by protection code, GREAD or WREAD privilege) is required to read 
file flags. Write access (by protection code, GWRITE, WWRITE, and/or SYSIO 
privilege) is required to set file flags. DATES is required to change last access 
date. SYSIO is required to set/clear the no-delete flag (P-bit). TUNE is required 
to set/clear file caching bits. 


To improve performance, use the DCL command LOAD/OVERLAY FILE_ 
UTILITY to move the code for this call into memory. To remove it from memory, 
use the DCL command UNLOAD/OVERLAY FILE_UTILITY. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
(md 
11 | file name in RADSO format | | 10 FQNAM1 
(2 words) 
13 12 
31 2-character(ASCIl) device name (disk only) | 30 FQDEV 
33 device unit ee 32 FQDEVN 


FIRQB+FQFIL- : You can also place a zero in this byte and specify the file by 
file specification (device, PPN, file name, and type). The system 
ignores the values in bytes 6 through 15 and 30 through 33 if you 
use a nonzero channel number. 
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FIRQB+FQSIZM 


FIRQB+FQPPN 
FIRQB+FQPPN+1 
FIRQB+FQNAM1 


FIRQB+FQEXT 


FIRQB+FQSIZ 


FIRQB+FQNAM2 


FIRQB+FQMODE 
FIRQB+FQFLAG 


FIRQB+FQPFLG 
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This byte contains the following internal flags: 
Bit Meaning When Set 
0 Set or reset file’s placed bit (cannot be used with bit 3). 


1 Used with bit 4 to return zero as the device cluster num- 
ber if file’s placed bit is not set. 


Change file’s backup statistics. 

Change file’s run-time system name field. 

Return file’s retrieval information. (Cannot be used with 
bit 3.) 

Reset file’s contiguous bit. 


Enable/disable sequential mode caching if file is cached. 
(Cannot be used with bit 3.) 


7 Enable/disable data caching on the file. (Cannot be used 
with bit 3.) 


The programmer number of the file you want to modify. 
The project number of the file you want to modify. 


The file name, in RAD50 format, of the file you want to modify. If 
FIRQB+FQFIL is nonzero, UU.FIL ignores these words. 


The file type, in RAD50 format, of the file you want to modify. If 
FIRQB+FQFIL is nonzero, UU.FIL ignores this word. 


If bit 3 of FIRQB+FQSIZM is set, the two words beginning at 
FIRQB+FQSIZ contain the new run-time system name in RAD50. 
If bit 4 of FIRQB+FQSIZM is set, the two words beginning at 
FIRQB+FQSIZ contain the file’s retrieval information. The moni- 
tor maps the virtual block number (VBN) of the file into the disk 
DCN. 

This byte contains the following flags: 

Bit Meaning When Set 


1 New value for placed bit if bit 0 of FIRQB+FQSIZM is set. 

2 New value for sequential bit if bit 6 of FIRQB+FQSIZM is 
set. 

3 New value for backup bit if bit 2 of FIRQB+FQCLUS is 
set. 

5 New value for P-bit (no delete/rename allowed) if bit 0 of 
FIRQB+FQCLUS is set. 

6 New value for ignore bit if bit 3 of FIRQB+FQCLUS is set. 

7 New value for cached bit if bit 7 of FIRQB+FQSIZM is set. 


Contains the new date of last access if bit 2 of FIRQB+FQSIZM is 


set. 


Contains the new date of creation if bit 2 of FIRQB+FQSIZM is 
set. 


Contains the new time of creation if bit 2 of FIRQB+FQSIZM is 
set. 


FIRQB+FQCLUS Two subfunction codes currently in use are: 
Bit Meaning When Set 


0 Change the value of the file’s P-bit (see FIRQB+FQNAM2). 


1 Do not return protection violation. If clear, and any of 
the requested functions cannot be executed, the monitor 
returns a protection violation error. If set, the monitor 
changes all valid requested functions and leaves the rest 
unchanged. 


Change the backup bit. 
Change the ignore bit. 


If file is opened (FQFIL not 0), use DLA in FIRQB+FQMODE 
if bit 2 of FIRQB+FQSIZM is set. 


Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 | LTGPET DER EEI LA) ELT 0 
5 | davies éietei umber Z 4 FQFIL 
7 a 6 FQPPN 
11 10 
13 12 
15 | file attribute data 14 
17 (unused words are padded with NULLs) 16 
21 | 20 
23 | 22 
25 | 24 
27 26 
31 30 
33 : 32 
35 | run-time system namie in RAD50 ional | 34 FQCLUS 
(2 words) 
37 36 
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FIRQB+FQFUN File characteristics: 
Bit Meaning When Set 


File is placed. 

File will be cached sequentially, if at all. 
File is set NOBACKUP. 

File is contiguous. 

Current setting of file’s P-bit. 

File is set IGNORE. 

File will be cached when open. 


If OF FP WD Ne 


Errors 


BADFUO _ File open is not a disk file or is a user file directory. 
NOSUCH _ File or account is not present on disk. 
NOTOPN = Channel is not open. 


PRVIOL File open is not a disk file or job lacks necessary privilege (see FIRQB+FQCLUS 
in data passed). 
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3.36.24 UU.HNG (Hang Up a Dataset) 


Privileges Required 


HWCTL is needed to hang up a dataset, exc 


calling job. 


Data Passed 


ept on a keyboard line owned by the 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 | LEITIAIIATIAT TTT 0 
FIRQB+FQSIZM Use one of the following values: 
377 Sets "Data Terminal Ready" to permit a modem con- 


nected to a RSTS/E system to dial out. If a connection 
is not made in 127. seconds, perform an automatic 


hang-up of the dataset. 
0 Hang up in two seconds. 
1-177 Hang up in 1 to 127. seconds. 


Data Returned 
The UU.HNG subfunction does not return any data. 


Errors 


BADFUO 


Illegal KB number or insufficient privileges to hang up a line owned by 


another job. 
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3.36.25 UU.JOB (Create Job) 


Privileges Required 


Set account access is required (GACNT or WACNT privilege) to spawn to another 
account. EXQTA is required to ignore job quota on spawn. JOBCTL is required 
to spawn a job even if no logins is set. TUNE is required to specify a priority 
when creating a job. WACNT is required to spawn a logged-out job. 


Data Passed — Logged-out job 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
: . 
ST en 
11 file name in RADS50 format 10 FQNAM1 
(2 words) 
13 12 
15 file type in RAD50 format (1 word 14. FQEXT 
17 | 16 FQSIZ 
21 10 bytes of 20 
information to be 
23 placed in created job’s 22 
core common area 
25 | 24 
27 26 
31 device name (2 ASCII characters) 30 FQDEV 
35 parameter word (see P.RUN) 34 FQCLUS 
37 ETITITIITETTITETTTT EE 36 
FIRQB+FQFIL The following bit flag is valid for a logged-out job: 
Bit Meaning When Set 
7 Create a job even if logins are disabled (JOBCTL privilege 
required). When this bit is not set, the job is created 
only if logins are enabled. If you do not have JOBCTL 
privilege, you must clear bit 7. 
FIRQB+FQPPN The project programmer number of the program to run. 
FIRQB+FQNAM1 The file name of the program to run, in RAD50 format. 
FIRQB+FQEXT The file type of the program to run, in RAD50 format. 
FIRQB+FQDEV Ten bytes of information to be placed into the created job’s core 
common area. Note that an eleventh byte is appended that 
contains the job number times 2 of the job that executed the SYS 
call. 
FIRQB+FQDEVN The device name and unit number of the program to run. 
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FIRQB+FQCLUS The parameter word to be passed to the program to run. The 
parameter word has exactly the same format and functions as the 
CCL command parameter word. Note that for jobs created under 
the BASIC-PLUS run-time system, the parameter word equals the 
program line number to which control is transferred when the job 
runs. 


Data Passed — Logged-in Job to Run a Program 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
FQSIZM5 KB to attach to | bit flags 4 FQEFIL 
7 | project number | 5 ener 7 6 FQPPN 
11 | file name in RAD5O format | 10 FQNAM1 
(2 words) | 

13 12 

17 | 16 FQSIZ 

21 20 FQBUFL 

23 22 FQMODE 

25 24 

27 26 

31 device name (2 ASCII characters) 30 FQDEV 


NOTE 


When you create a logged-in job, the system gives the new job a copy of 
the core common, the logicals, and the command line recall buffer. 
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FIRQB+FQFIL The following bit flags are valid when you create a logged-in job to 
run a program. 


Bit Meaning When Set 


1 Do not pass the user logicals of the creating account to the 
new job. (The contents of core common are still passed.) 


2 Create the new job with no privileges. 


Create the new job with the authorized privileges of the 
new job equal to the authorized privileges of the job’s 
account that are also current privileges of the calling job. 
If Bit 3 is clear, the new job is created with the authorized 
privileges of the job’s account. 


5 Create a job to run under account specified at FIRQB+FQSIZ 
(GACNT or WACNT privilege required). 
6 Create a logged-in job. You must set this bit. The new job 


runs under the caller’s account unless you also set bit 5. 


7 Create a job even if logins are disabled (JOBCTL privilege 
required). When this bit is not set, the job is created 
only if logins are enabled. If you do not have JOBCTL 
privilege, you must clear bit 7. 

Clear all bits you do not use. 


FIRQB+FQSIZM Bits 0-6 indicate keyboard number to attach to. To specify KBO:, 
set bit 7 to one. A zero byte indicates a detached job. 

FIRQB+FQPPN The PPN of the programto run. 

FIRQB+FQNAM1 The file name of the program to run, in RAD5O format. 

FIRQB+FQEXT The file type of the program to run, in RAD50 format. 

FIRQB+FQSIZ Account under which job runs (GACNT or WACNT privilege 


required; bit 5 at FIRQB+FQFIL must be set). If you do not have 
the necessary privileges, set both bytes to 0. 


FIRQB+FQBUFL Priority of the new job (requires TUNE privilege). If you specify 0, 
the system uses the caller’s values. Use bit 8 to explicitly specify 
priority 0. Users without TUNE privilege must set this byte to 0. 
Note that if you create the job on a pseudo keyboard, the system 
reduces the priority to the controlling job’s priority. 


FIRQB+FQBUFL+1 Run burst of the new job (requires TUNE privilege). Use one to 
explicitly specify priority zero. If you specify 0, the system uses 
the caller’s values. Users without TUNE privilege must set this 
byte to 0. 


FIRQB+FQMODE Maximum job size of the new job (requires TUNE privilege). If 
you specify 0, the system uses the caller’s values. Users without 
TUN E privilege must set this byte to 0. 


FIRQB+FQDEV Device name, as two ASCII characters, for the program to run. 
FIRQB+FQDEVN Device unit number for the program to run. 
FIRQB+FQCLUS The parameter word to be passed to the program to run. The 


parameter word has exactly the same format and functions as the 
CCL command parameter word. Note that for jobs created under 
the BASIC-PLUS run-time system, the parameter word equals the 
program line number to which control is transferred when the job 
runs. 
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Data Passed — Logged-in Job to Enter a Keyboard Monitor at P.NEW 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


LATED EEETTA EID ELE GA 


UU.JOB (= 30) // 4 IIIT 
ee 


run-time system name in RADS5O0 format 
(2 words) 


1 


FQFUN 3 


FQSIZM5 4 FQFIL 


7 6 FQOPPN 


11 10 FQNAM1 


13 | 


77777700 
ee 
77777700 
C__rinnnieon 


NOTE 


15 14 FQEXT 


17 16 FQSIZ 


21 20 FQBUFL 


23 22 FQMODE 


25 


27 


31 


33 


35 


37 


When you create a logged-in job, the system gives the new job a copy of 
the core common, the logicals, and the command line recall buffer. 
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FIRQB+FQFIL The following bit flags are valid when you create a logged-in job to 
enter a keyboard monitor. 


Bit Meaning When Set 


1 Do not pass the user logicals of the creating account to the 
new job. (The contents of core common are still passed.) 


2 Create the new job with no privileges. 


3 Create the new job with the authorized privileges of the 
new job equal to the authorized privileges of the job’s 
account that are also current privileges of the calling job. 
If Bit 3 is clear, the new job is created with the authorized 
privileges of the job’s account. 


4 Enter keyboard monitor instead of running a program. 
(You must set this bit.) 
5 Create a job to run under account specified at FIRQB+FQSIZ 
(GACNT or WACNT privilege required). 
6 Create a logged-in job. (You must set this bit.) The new 
job runs under the caller’s account unless you also set bit 
5. 
7 Create a job even if logins are disabled (JOBCTL privilege 


required). When this bit is not set, the job is created 
only if logins are enabled. If you do not have JOBCTL 
privilege, you must clear bit 7. 

Clear all bits you do not use. 


FIRQB+FQSIZM Bits 0-6 indicate keyboard number to attach to. To specify KBO:, 
set Bit 7 equal to one. The value of zero (detached job) is not 
allowed. 


FIRQB+FQNAM1 The run-time system you specify must be installed and must be a 
| keyboard monitor. Specify zero for the system’s default keyboard 
monitor (DCL). 


FIRQB+FQSIZ Account under which job runs (GACNT or WACNT privilege 
required; bit 5 at FIRQB+FQFIL must be set). If you do not have 
the necessary privileges, set both bytes to zero. 

FIRQB+FQBUFL Priority of the new job (requires TUNE privilege). If you specify 0, 
the system uses the caller’s values. Use bit 8 to explicitly specify 
priority 0. Users without TUNE privilege must set this byte to 0. 
Note that if you create the job on a pseudo keyboard, the system 
reduces the priority to the controlling job’s priority. 

FIRQB+FQBUFL+1 Run burst of the new job (requires TUNE privilege). Use one to 
explicitly specify priority zero. If you specify 0, the system uses 
the caller’s values. Users without TUNE privilege must set this 
byte to 0. 


FIRQB+FQMODE Maximum job size of the new job (requires TUNE privilege). If 
you specify 0, the system uses the caller’s values. Users without 
TUNE privilege must set this byte to 0. 


FIRQB+FQDEV Device name, as two ASCII characters, for the program to run. 
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Data Returned (all types of jobs) 


FIRQB 


Mne- Octal. | Octal Mne- 
monic Offset Offset monic 


Errors 


BADFUO 


NOBUFS 


NODEVC 
NOROOM 


NOSUCH 


NOTAVL 


0 


[ernie 
[iis 
ie _| 
[ine 
[ermine 


2 FQJOB 
4 FQFIL 


6 


10 


12 


14 


16 


20 


22 


24 


26 
30 
32 
34 


36 


You specified a keyboard monitor at FIRQB+FQNAM1, but did not supply a 
keyboard number at FIRQB+FQSIZM. 


You are trying to create a logged-in job, but not enough XBUF is available 
for temporary storage of your current job’s core common. 


The keyboard number at FIRQB+FQSIZM is invalid. 
Job cannot be created. Probable causes: 


e Logins are disabled and bit 7 (value = 200) at FIRQB+FQFIL is clear. 
e The system’s job or swap slots are currently full. 


You have the necessary privilege and are trying to create a logged-in job, 
but the system cannot log the job in. Possible causes are that you specified 
a nonexistent account or an expired account. 


The keyboard specified at FIRQB+FQSIZM is open, is in use, or is not 
assigned to the calling job. A user without DEVICE privilege can also get 
this error if the system manager has restricted the device. 
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PRVIOL You do not have the required privileges and tried to: 


e Create a job when logins were disabled. 
e Create a logged-out job. 
e Create a job to run under an account other than the current account. 


e¢ Create a detached job that would cause you to exceed your detached job 


quota. (This quota is set by your system manager; its default value is 
Zero. ) 


Note that when you create a logged-in job, you can also get any error that can 
occur for the UU.LIN (Login), .RUN, and .RTS directives, because the monitor 
executes these directives for the new job. If an error occurs, the monitor kills the 
new job and returns the error to your job instead. 
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3.36.26 UU.LIN (Login) 


Privileges Required 


Set account access (GACNT or WACNT) is required to check the password of any 
account. Also, DEVICE is required if the device is restricted. 


Data Passed—Login Function 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


1 Pere rereeererr eo gs wir! 0 

FQFUN 3 UU.LIN (= 4) LAT TTY 2 

FQSIZM5 function flag FELLA TSA 4 

11 10 FQNAMI1 

password in RAD50 format 

13 (2 words) 12 

15 | or 14 

17 password in ASCII format 16 

(14 bytes) 

21 20 

23 22 

25 24 

27 VAETLAT LAL PELE LAE EP LL 26 

31 VIAATEATALLL TEE Te 30 

33 PELLET ATA TATA TAL ATT 32 

35 LIPTIIAIIATTAT TITTY 34 

37 EDA DLAELALATANSD AT TEL 36 
FIRQB+FQSIZM The function flag bits are: 

Bit Setting Meaning 

0 Clear Must be clear for the login function. 

1 Clear The monitor assumes the password is six 
characters in RAD50 format. The password 
is converted to ASCII before comparison. 

Set The monitor assumes the password is 14 
bytes of ASCII data. 

In either case, the password must not contain a question mark (?). 

3 Clear The monitor performs the password check. 
No privileges are required. 

Set The monitor suppresses the password check. 
However, GACNT or WACNT is required. 
FIRQB+FQPPN PPN for the account being logged into. It must not be in group 


[0,*]. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 

1 LLIIITIITITT ATA AT 0 

5 total number of jobs under this account |} 4 FQFIL 

7 | detached job no. (2) detached job no. (1) 6 FQPPN 
11 10 FQNAM1 
13 | | 12 
15 | 14 

zero byte marks end of list 
17 | of detached job numbers. | 16 
21 only the first 25. detached 20 
job numbers are returned. 
23 22 
25 24 
27 26 
31 30 
33 32 
35 34 
37 36 
FIRQB+FQFUN On successful return, indicates where the log-in operation has 
been completed. Values are: 

Value Meaning 

-1 Success—the job is logged in to the new account. 

-2 Detached job quota exceeded. Job is not logged in and 
remains in the old account; attach instead to some job 
from the list starting at offset FQNAM1. 

>0 Total job quota exceeded. Job is not logged in and 
remains in the old account; the value returned is the 
actual job quota. If there are any detached jobs, you 
can attach to one. 

Errors 
BADDIR The account does not have all the necessary directory structures. 
NOBUFS No buffers are available to create the necessary internal structures. 
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NOSUCH The monitor returns this error code if: 


The password specified at FIRQB+FQNAM1 does not match the pass- 
word of the account on the system or contains question marks. 

The PPN specified at FIRQB+FQPPN does not exist or the project 
number is zero. 

System password validation is required for this type of job, and the ac- 
count is marked "no-lookup," but the "verify system password" function 
has not yet been successfully executed. 


NOTAVL The monitor returns this error code if: 


The PPN specified at FIRQB+FQPPN is expired or is marked as "no- 
interactive.” 


The account is flagged as "no-dial-up" or "no-network" and the job is a 
dial-up or network job. 


Data Passed—Verify Password Function 


Mne- Octal 
monic Offset 


FIRQB 


Octal Mne- 
Offset monic 


1 0 

FQFUN 3 2 

FasiZMs miimnin | 4 
11 | 10 FQNAM1 

password in RAD50 format 

13 (2 words) 12 

15 or 14 

17 password in ASCII format 16 

(14 bytes) 

21 20 

23 22 

25 24 
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FIRQB+FQSIZM The function flag bits: 


Bit Setting Meaning 

0 Set The verify password function is performed. 
The caller supplies the password to verify in 
FIRQB+FQNAM1. 

1 Clear The monitor assumes the password is six 


characters in RAD50 format. The pass- 
word is converted to ASCII data before 
verification. 


1 Set The monitor assumes the password is 14 
bytes of ASCII data. 
In either case, the password must not contain any question marks. 


FIRQB+FQPPN A value of zero means use the caller’s PPN. 
FIRQB+FQDEV Device name of the disk on which to check. You must 
FIRQB+FQDEVN have DEVICE privilege if the device is restricted. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.LIN subfunction does 
not return any meaningful data. 


Errors 


BADNAM Passwords do not match. 
DEVNFS Device specified is not a disk. 


NOSUCH Account specified is a nonuser account (no password data present) or does 
not exist. 
PRVIOL Caller does not have required privilege. 


3.36.26.1 Verify System Password Function 


This function verifies the system access password, if any. If there is no system 
access password, or if the password check has already been performed, the 
function returns successfully. Otherwise, the monitor compares the password 
supplied with the system password. A match sets a job flag which is tested by the 
login function; a mismatch generates the NOSUCH error. 


For compatibilty with old programs that perform a password lookup and then 
login, the login function does not require a system password on accounts where 
password lookup is allowed. 
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Data Passed—Verify System Password Function 


Mne- Octal 
monic Offset 


1 

FQFUN 3 
FQSIZM 5 
7 

11 

13 

15 

17 

21 

23 

25 

27 

31 

33 

35 


37 


FIRQB 
Octal 
Offset 
. 
: 
; 
LUTE TTA ATA TTT LAT 6 
[_ -—<C~S:S 10 
12 
14 
password in ASCII format | 16 

(14 bytes) 
20 
22 
24 
: 
: 
: 
. 
: 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.LIN subfunction does 
not return any meaningful data. 


Errors 


NOSUCH 


Password did not match the system password. 


Mne- 
monic 


FQNAM1 
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3.36.27 UU.LOG (Set Number of Logins) 


Privileges Required 


SWCTL is required to set the number of logins. 


Data Passed 


Mne- Octal 
monic Offset 


1 


FQFUN 3 


FIRQB+FQFIL 
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FIRQB 
Octal Mne- 
Offset monic 


REG eaerveeeese caee ie: 


UU.LOG (= -23) 


VIII IIIA FQFIL 


PTATTTAT ET IAAT AT LAT 


A value of zero sets the number of allowed jobs to one. The upper 
limit for the number of logins is either the system JOB MAX or 
the number of jobs that can currently be swapped, whichever is 
lower. If you specify a larger value, the system sets the number of 
logins to the upper limit. In this case, no error is returned. 


Data Returned 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


PEL DTTTA IIIT TAL 0 
| 2 FQJOB 
| 4 FOFIL 


Errors 
No errors are possible with the UU.LOG subfunction. 
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3.36.28 UU.LOK (Disk Directory Lookup by File Name/Wildcard Lookup) 


Privileges Required 


DEVICE is required to do a directory lookup on a restricted device. Read or 
execute access (by protection code, GREAD or WREAD privilege) is required to 
lookup another account. 


Data Passed — Look Up by File Name 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


amin 
neem 


file name in RAD50 format 
(2 words) 


Penni 
<>0, unit ian: real | device unit number 


FIRQB+FQPPN PPN of the file to look up. Zero in both bytes means the current 


account is used. 


1 


FQFUN 3 
4 FQFIL 
6 FQPPN 


10 FQNAM1 


14 FQEXT 


30 FQDEV 


32 FQDEVN 
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Data Returned — Look Up by File Name 


Mne- 


FIRQB 
Octal Octal Mne- 


monic Offset Offset monic 


0 


[in] 
TT Te 


2 FQJOB 


4 FQFIL 


6 FQPPN 


file name in RAD50 format 10 FQNAM1 


(2 words) 


| 14 FQEXT 


| 16 FQSIZ 


20 FQNAM2 


22 FQMODE 
24 FQFLAG 


26 FQPFLG 


device name (disk) (2 ASCII characters) 30 FQDEV 


<>0, unit number real device unit number 
file cluster size 
file identification index 


32 FQDEVN 
34 FQCLUS 


36 FQNENT 


FIRQB+FQMODE System internal format for dates is: 
FIRQB+FQFLAG [(year - 1970.) * 1000.] + day-within-year 
FIRQB+FQPFLG Time is in minutes until midnight, where 1440. equals midnight. 


Errors 


See the .DATE directive for a discussion of these formats. 


BADNAM The file name at FIRQB+FQNAM1 is missing or invalid. 


NOSUCH 


PAKLCK 


Device specified at FIRBQ+FQDEV is not a disk, or the file specified does 
not exist on the disk. This error also occurs when a user does not have read 
or execute access to the specified file. 


The disk is restricted and the account under which the call is executed does 
not have DEVICE privilege. 
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Data Passed — Disk Wildcard Directory Lookup 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


277700 
sroaraniniee number 


1 


FQFUN 3 


5 4 FQFIL 


7 6 FQPPN 


11 wildcard file name in RAD50 format 10 FONAM1 
(2 words) 


13 


15 |wildcard file type in RAD50 format (1 word) 14 FQEXT 


17 LAL ITATAT ALATA GA 


21 


VITITEATALAT AAT I PALL 


23 22 FQMODE 


marked-for-delete flag 
25 LLTAALTALTAATALAPALA LT, 


27 IEPA TTALATAL ELTA PL LLY 


31 


30 FQDEV 


VILITAL ITAL TIS aT IATA 
eee ae a ee ae ee | 


FIRQB+FQFIL The index number, telling the directive to return the first n+1 
examples. If the value is zero, then the first file matching the 
wildcard specification is returned; if the value is one, then the 


second file. This continues until there are no more matching files 
and the NOSUCH error returns. 


FIRQB+FQPPN Zero in both bytes means the current account. 


FIRQB+FQNAMI1 RAD50 representation of a wildcard file name specification, where 
a question mark (?) can replace any character in the file name. 
Used with the file type in FIRQB+FQEXT to create a wildcard 
file specification. You can use .FSS to help construct the wildcard 
name. 


FIRQB+FQEXT RAD50 representation of a wildcard file type specification, where a 
question mark (?) can replace any character in the file type. Used 
with the file name in FIRQB+FQNAM1 to create a wildcard file 


specification. 


FIRQB+FQMODE Bit 14 set causes the monitor to return information about marked- 
for-delete files. 


| device name (disk) (2 ASCII characters) 
| 


33 32 FQDEVN 


35 


37 
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Data Returned — Disk Wildcard Directory Lookup 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 7 ET —_ 0 
5 | _ “(same as er passed) a 4 FQFIL 
7 spreieet number ; 6 FQPPN 
11 file oe oanee | 40 FQNAMI 
(2 words) 
13 | 12 
15 | file type i in RADSO ooo word) | 1 14 FQEXT 
23 “date of last : access (disk only) 22 FQMODE 
FIRQB+FQNENT+1 This byte contains the following internal flag information: 
Bit Meaning When Set 
1 File is placed 
2 Some job has write access now 
3 File is open in update mode 
4 File is contiguous; no extend allowed 
5 No delete or rename allowed 
7 File is marked for deletion 
Errors 
BADNAM The file name at FIRQB+FQNAM1 is missing or invalid. 
NOSUCH Device specified is not a disk or no file corresponds to the index given. 
PAKLCK The disk is restricted and the account under which the call is executed does 


not have DEVICE privilege. 
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3.36.29 UU.MNT (Disk Pack Status) 


Privileges Required 


You need HWCFG privilege to declare a mounted disk as restricted or unre- 
stricted. You need SWCTL privilege to load or unload the Storage Allocation 
Table (SAT) of the specified disk into or out of memory. You need MOUNT 


privilege to: 


¢ Mount or dismount a shared disk 

¢ Dismount a /NOSHARE disk owned by another job 
¢ Mount a disk /NOSHARE for a job running under another PPN 
e Mount a dirty disk 


Data Passed 


FIRQB 


Mne- Octal Octal 


monic Offset 


1 

FQFUN 3 
FQSIZM5 
7 

14 

13 

15 


17 


21 | 


23 | 


25 
27 
31 
33 
35 


37 
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: 

Pomarea [n | 2 

: 

| Sack identification label in RAD50 ‘aienat 10 

(2 words) 

12 

: 

, logical name fai disk in RADSO format 16 
(first 2 words) 

| 20 

22 

24 

VAT ATID TTATAL IAT TI SL 26 

| device name (2 ASCII characters) 30 


Mne- 
monic 


FQEFIL 


FQNAM1 


FQEXT 
FQSIZ 


FQMODE 
FQFLAG 


FQDEV 
FQDEVN 


FIRQB+FQFIL The subfunction codes are: 
Code Meaning 


0 Mount a disk pack or cartridge 

2 Dismount a disk pack or cartridge 
4 Restrict a disk pack or cartridge 

6 Unrestrict a disk pack or cartridge 


10 Load the SAT of a disk into memory 
12 Unload the SAT of a disk from memory 


14 Reserved for future use 
16 Return disk drive status information 
FIRQB+FQSIZM Job number of the intended owner. Applies only if bit 11 is set in 


FIRQB+FQMODE. Zero means the caller’s job number, If bit 11 
in FIRQB+FQMODE is clear, this byte should be zero. 


FIRQB+FQNAM1 For mount function: pack ID of pack to mount. Must be supplied 
unless bit 10 is set in FQMODE. 


FIRQB+FQMODE The bits in the mode word are: 
Bit Meaning 
8 Mount Level 1.2 disk with /NOQUOTA 
10 Mount with lookup of pack ID 
11 Mount disk for use by single user ((NOSHARE) 


12 Mount disk read/write, even if disk was initialized as 
read-only 


13 Mount disk read-only 
14 Mount as a private disk (/PRIVATE) 
15 Must be set if any of the above bits are set 


You can set one bit or a combination of bits. 
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Data Returned 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne- 
Offset monic 


. . 
5 UNTCNT word | 4 FQFIL 
17 | size of SAT in bytes (first word) or | 16 FQSIZ 
logical name for disk in RAD50 format 
21 (2 words) 20 
25 | 3rd word of logical name for disk (RAD50). | 24 FQFLAG 
33 LEAL ALIPALTI ET TA IATA 32 
FIRQB+FQFIL The internal UNTCNT value for the specified disk, if the subfunc- 
tion code is 16 in FIRQB+FQFIL of the data passed. 
FIRQB+FQPPN The CSR value for the specified disk, if the subfunction code is 
16 in FIRQB+FQFIL of the data passed. The disk does not exist 
if this value is 0. If a CSR is returned, the specified unit may or 
may not exist. 
FIRQB+FQNAM1 The controller number if the specified disk is a DU type disk, and 
if the subfunction code is 16 in FIRQB+FQFIL of the data passed. 
Otherwise, this value is random. 
FIRQB+FQNAM1+2 The internal UNTOPT value for the specified disk, if the subfunc- 
tion code is 16 in FIRQB+FQFIL of the data passed. 
FIRQB+FQEXT The internal drive type identifier for the specified disk, if the 
subfunction code is 16 in FIRQB+FQFIL of the data passed. 
FIRQB+FQSIZ For subfunction 10, RSTS/E returns the amount of memory in 
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bytes that was used to load the SAT in FIRQB+FQSIZ. For other 
subfunctions, RSTS/E returns the first two words of the logical 
name for the disk. The third word of the logical name is in 
FIRQB+FQFLAG. 


Errors 


BADFUO 
BADPAK 


DEVNFS 


HNGDEV 


INTPAK 


INUSE 
NOBUVFS 
NODEVC 
NOTCLS 
NOTMNT 


NOTOPN 
PRVIOL 


WRGPAK 


You tried to mount a disk that is already mounted or that resides in a 
nondismounted drive, or drive specified is the system disk. 


Disk directory structure is invalid. For example, the cluster size is larger 
than 16 or the SAT is unreadable. 


You tried to restrict, unrestrict, or dismount a disk currently open in non- 
file-structured mode. Or, you tried to load or unload the SAT of a disk 
currently open in non-file-structured mode. 


You tried to mount a disk that is not write-enabled or you tried to load the 


SAT of a read-only disk. 


The SAT on the disk needs to be rebuilt because the disk was not properly 
dismounted when it was last used. Before using the disk, use the ONLCLN 
program to rebuild the SAT. 


NOTE 


The MOUNT command automatically per- 
forms the rebuild operation if it is needed. 


Note that when this error occurs, the mount succeeds, but the disk is always 
mounted read-only with the "dirty" bit set. (You can see if this bit is set by 
looking at the output of the SHOW DISK command which reports that the 
disk is "dirty.") 

You tried to dismount a disk with an open file. 

You tried to load the SAT and there is no memory available. 

Device type or unit at FIRQB+FQDEV is not on the system. 

You tried to load the SAT more than once. 


You tried to lock, unlock, or dismount a disk that is not mounted. Or, you 
tried to load or unload the SAT of a disk that is not mounted. 


You tried to unload the SAT of a disk that was not loaded. 
You tried to mount a disk that does not contain the RSTS/E file struc- 


ture. Use the INITIALIZE command, the online DSKINT program, or the 


DSKINT initialization option to initialize the disk. You do not have the 
required privilege to load or unload the SAT. 


You tried to mount a disk with an incorrect pack label. 
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3.36.30 UU.NAM (Associate a Run-Time System with a File) 


Privileges Required 


File write access (by protection code or GWRITE, WWRITE, and/or SYSIO 
privilege) is required to set the run-time system name for a file. 


Data Passed 


FIRQB 
Mne— Octal Octal Mne— 
monic Offset Offset monic 


1 EG LALEATTA AA EACIAG ELT 0 

FQFUN 3 UU.NAM (= —21) LLPITT ALLY 2 
FQSIZM 5 run—time | channel number —_| 4 FQFIL 
7 system name in RAD50 format 6 FQPPN 

1" (2 words r 


Data Returned 


Other than a possible error in byte 0 of the FIRQB, the UU.NAM subfunction 
does not return any meaningful data. 


Errors 


NOTOPN Channel is not open. 


PRVIOL File open on channel is not a disk file or the job executing the call does not 
have write access. 
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3.36.31 UU.NLG (Disable Further Logins) 


Privileges Required 
SWCTL is required to disables logins. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[iin 
| LITT EITIITIT TTA 


LTATATAAT ATTA LAT Ed 


Data Returned 
The UU.NLG subfunction does not return any meaningful data. 


1 
FQFUN 3 


5 


7 


11 


13 


15 


17 


21 


23 


25 


27 


31 


33 


35 


37 


Errors 
No errors are possible with the UU.NLG subfunction. 
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3.36.32 UU.ONX (Open Next Disk File) 


This call opens a disk file or a series of disk files matching a wildcard spec- 
ification. UU.ONX requires an I/O channel to use and grants access to the 
file. 


When you attempt an open next on a closed channel, UU.ONX finds the first 
file that matches the specification. When you attempt an open next on an open 
channel, UU.ONX finds the next file that matches the specification. If there are 
no more files that match the specification, UU.ONX closes the channel. 


Privileges Required 


DEVICE is required to perform an open next on a restricted disk. File read 
access (by protection code, or GREAD or WREAD privilege) is required to perform 
an open next for read access. File write access (by protection code, or GWRITE, 
WWRITE, and/or SYSIO privilege) is required to perform an open next for write 
ACCESS. 


Data Passed 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset olset monic 


file name in RAD50 format 
(2 words) 


ee name ° (2 ASC snare) must be disk 


FIRQB+FQPPN The file owner’s PPN. Zero indicates the current account. Wildcards 
are not permitted in the specification. 


FIRQB+FQNAM1 The name of the file in RAD50 format. The name may contain 


wildcard characters (question marks, ?). 


1 


FQFUN 3 


5 4 FQFIL 


7 6 FQPPN 


11 10 FQNAM1 


13 


15 14 FQEXT 


17 


21 


23 22 FQMODE 


25 


2/7 


31 30 FQDEV 


33 32 FQDEVN 


35 


37 
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FIRQB+FQEXT 


FIRQB+FQMODE 


FIRQB+FQDEV 


FIRQB+FQDEVN 


The type of the file in RAD50 format. The type may contain wild- 
card characters (question marks, ?). 


The OPEN modes currently defined are: 


Decimal 


0. 


eS 


16. 


32. 


256. 

2048. 
4096. 
8192. 


16384. 
32768. 


Octal 
0 

1 

2 

4 

10 


20 


40 


400 
4000 
10000 
20000 
40000 


100000 


Function 

Normal read/write 
Update 

Append 

Guarded update (4 + 1) 


Special extend (RSTS/E updates file’s 
size and retrieval pointers during 
extend operations) 


Do not update access dates to files; 
do not grant write access (requires 


DATES privilege) 


Do not grant any access to files (direc- 
tory lookup only) 


User data caching 

Sequential data caching (with 400) 
Read normally regardless 

Open file read-only 

Include files marked-for-delete 


Mode bits are real; this must be spec- 
ified for the other open bits to be 
tested 


The device name; must be a disk. Zero in both bytes indicates "SY", 
the public disk. 


The device unit number. A nonzero value in the high byte 
(FIRQB+FQDEVN+1) indicates an explicit device unit number 
in the low byte. A zero value in FIRQB+FQDEVN+1 indicates no 


unit number. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic lise! Offset monic 


as 


file name in RAD50 format 
(2 words) 


protection code 
ere ee ABE hs 
a Tae 


FIRQB+FQSIZM For large disk files (greater than 65,535 blocks), this byte contains 
the MSB of the file’s size in 512-byte blocks. This byte is combined 
with the word at FIRQB+FQSIZ to form a 24-bit field giving the 


1 


3 2 FQJOB 


FQSIZM 5 4 FQFIL 
6 FQPPN 


10 FQNAM1 


14 FQEXT 
16 FQSIZ 
20 FQBUFL 
22 FQMODE 
24 FQFLAG 


26 FQPFLG 


30 FQDEV 

32 FQDEVN 
34 FQCLUS 
36 FQNENT 


file size. 

FIRQB+FQPPN The PPN under which the file is open. 

FIRQB+FQNAM1 The file name; two words of RAD50 data. 

FIRQB+FQEXT The file type; one word of RAD50 data. 

FIRQB+FQSIZ The LSB of the file’s size in 512-byte blocks. (See FIRQB+FQSIZM.) 

FIRQB+FQBUFL The date of last access to the file. 

FIRQB+FQMODE The date of creation of the file. 

FIRQB+FQFLAG The time of creation of the file. 

FIRQB+FQPFLG The file cluster size, modulo 256. That is, a file cluster size of 256 
is indicated by a value of zero. 

FIRQB+FQPROT The protection code of the file. 

FIRQB+FQDEV The device name, as two ASCII characters. 

FIRQB+FQDEVN The device unit number. 

FIRQB+FQCLUS The file identification index of the file. This word can be used 


instead of the file name in subsequent opens of the file. The file 
identification index is provided for compatibility with RSX. 


3-346 .UUO—UU.ONX 


FIRQB+FQNENT The description of the device just opened. The low byte contains 


Errors 


BADFUO 


DEVNEFS 
HNGDEV 
NOSUCH 
NOTMNT 
PAKLCK 


the device’s handler index. The high byte contains a set of sta- 
tus flags to allow for device-independent I/O routines. (See the 
OPNFQ subfunction of CALFIP.) 


The parameters passed in the call are inconsistent with the currently open 
channel. 


You tried to open a device that is not a disk. 

Device is hung or write-locked. 

No more files match the specification. The channel is closed. 
The device is not mounted. 


The disk pack is restricted. You need DEVICE privilege to open a restricted 
disk. 
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3.36.33 UU.PAS (Create User Account) 


Privileges Required 


Set account access (GACNT or WACNT) is required to create an account. 


Data Passed (Updated Format) 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset Offset monic 
| 
[wars nm | 
13 a | | 7 : 12 
password (2 words in RAD50 format) 
15 14 
27 PETTLLLLLTALTTAL LALLA 26 FQPFLG 
31 device name (2 ASCII characters) 30 FQDEV 
33 a6) unit ay real 32 FQDEVN 
FIRQB+FQFIL Zero means preextend one cluster. 1-7 means preextend specified 
number of clusters. 
FIRQB+FQSIZM Flag byte. Bit 7 set means data passed in the FIRQB is in the 


updated format. If bit 7 is clear, the data is in the V8.0 format. 
Other bits are reserved. 


FIRQB+FQPPN The device cluster number to place UFD. Minus one means place 
UDFD at the midpoint of the disk. If the cluster is not available, 
the directive uses the next highest available cluster number. 


FIRQB+FQNAM1 The PPN being created. 


FIRQB+12 Optional password in RAD50 format, two words long. This is 
provided for compatibility. Digital strongly recommends that you 
use longer passwords for greater security. Specify zero here to 
create a noninteractive account with no password. The account 
can be made interactive later by setting a longer password using 


UU.CHU. 
FIRQB+FQSIZ The logged-out quota in blocks. 
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FIRQB+FQFLAG+1 


FIRQB+FQBUFL 


FIRQB+FQMODE 
FIRQB+FQFLAG 


FIRQB+FQCLUS 


Data Returned 


Mne- Octal 
monic Offset 


FIRQB+FQSIZ and the MSB are in FIRQB+FQFLAG+1. Use 377 
in all three bytes for an unlimited quota. Zero in all three bytes 
means no blocks can be allocated. 


The expiration date in RSTS format: year - 70 + day of vear. 
Minus one means the account does not expire. This is the default. 


The logged-in quota in blocks. The LSB are in 


FIRQB+FQMODE and the MSB are in FIRQB+FQFLAG. Use 377 
in all three bytes for an unlimited quota. Zero in all three bytes 
means no blocks can be allocated. 


The UFD cluster size. It must be greater than or equal to the 
pack cluster size and a power of two from 1-16. Zero means the 
account uses the pack cluster size. 


FIRQB 
Octal Mne- 
Offset monic 


(amid 
5 4 
7 6 
11 10 
13 12 
15 14 
17 16 
21 20 
23 22 FQMODE 
25 24 FQFLAG 
27 26 FQPFLG 
31 30 FQDEV 
33 32 FQDEVN 
35 34 FQCLUS 
37 36 FQNENT 
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Data Passed (Pre-V9.0 Format) 


Mne— Octal 
monic Offset 


3 | UU.PAS (=0) | TT LITIIT 2 
FQSIZM 5 p flags | preextnd UFD clstrs 4 FQFIL 

7 device cluster number for UFD or -1 6 FQPPN 

13 | 12 
password (2 words in RAD50 format) 

15 14 
17 number of blocks for quota; 0 = unlimited 16 FQSIZ 
21 expiration date | 20 FQBUFL 
23 | LALTATALT AD IAAT AT AGT 22 
25 CTEIALAT IAT AT Aa ad 24 
27 LPITEATALIT AAA LAT ET aT | 26 
31 device name (2 ASCII characters) 30 FQDEV 
35 UFD cluster size (O=use pack cluster size) 34 FQCLUS 
37 CEL TLAL ELE EET EL ETT 36 

FIRQB+FQFIL Zero means preextend one cluster. 1-7 means preextend specified 
number of clusters. 

FIRQB+FQSIZM Flag byte. Bit 7 set means data passed in the FIRQB is in the 
updated format. If bit 7 is clear, the data is in the V8.0 format. 
Other bits are reserved. 

FIRQB+FQPPN The device cluster number to place UFD. Minus one means place 
UFD at the midpoint of the disk. If the cluster is not available, 
the directive uses the next highest available cluster number. 

FIRQB+FQNAM1 The PPN being created. 

FIRQB+12 Optional password in RAD50 format, two words long. This is 
provided for compatibility. Digital strongly recommends that you 
use longer passwords for greater security. Specify zero here to 
create a noninteractive account with no password. The account 
can be made interactive later by setting a longer password using 
UU.CHU. 

FIRQB+FQBUFL The expiration date in RSTS format: year - 70 + day of year. 
Minus one means the account does not expire. This is the default. 

FIRQB+FQCLUS The UFD cluster size. It must be greater than or equal to the 


Data Returned 


LITTTTTTTAITI ITAA | 0 


FIROB 
Octal Mne— 
Offset monic 


pack cluster size and a power of two from 1-16. Zero means the 
account uses the pack cluster size. 


Same as for the updated format. 
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Errors 


ABORT 


BADCLU 
BADCNT 


DEVNFS 
FIEXST 
NOROOM 


PRVIOL 


The account has been entered, and the directory has been preextended. 
However, the account has not been given a password or quota because 
an internal consistency check has failed. Submit an SPR if you get this 
error, and include: 


e A copy of the disk. 


e Asnap shot dump. (Use the DUMP/SYSTEM command to copy 
the contents of memory to CRASH.SYS, then run the ANALYS 
program to save the information. Submit a listing that contains 
the ANALYS program’s output.) 


See the RSTS/E System Manager’s Guide for more information on 
ANALYS. 


Cluster size is nonzero and is less than the pack cluster size. 


The number of clusters specified at FIRQB+FQFIL: 


e Is out of range. 


e When added to the device cluster number specified at FIRQB+FQPPN 
yields an effective address that is greater than the disk size. (See 
Appendix B for disk size information.) 


Device is not a disk or the disk is open in non-file-structured mode. 
Account specified already exists on device. 


The monitor cannot allocate one cluster for the UFD you are creating 
because the disk is full. 


PPN is [0,0], or either the project number or programmer number is 
255. 
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3.36.34 UU.POK (Poke Memory) 


Privileges Required 
SYSMOD is required to write into kernel memory. 


Data Passed 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset Offset monic 


1 | TITILITITITIITATITTAT 0 
FQFUN 3 LI ftttitii | 2 
21 TLEALALITTL ILIA TAL ad | 20 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.POK subfunction does 
not return any meaningful data. 


Errors 


PRVIOL The job executing the call does not have SYSMOD privilege or the address 
specified is odd. 
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; 


3.36.35 UU.PPN (Wildcard PPN Lookup) 


Privileges Required 


DEVICE is required to perform a lookup on a restricted device. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


Temi | 
[ier 


device name (2 ASCII chars)— must be disk 


<>0, unit no. real device unit number 


LIITTITTTITTT TTT TET | 


PELPALATI TAL TAA TA 


FIRQB+FQFIL The index. The directive returns the n+1th instance. If n is zero, 
the directive returns the lowest PPN that matches the wildcard 
specification; if n is one, it returns the next lowest, and so forth, 
until there are no matching files. 


FIRQB+FQPPN 377 represents a wildcard. Use 377 in both bytes to represent 
any account, that is, [*,*]. Use zero in both bytes to indicate the 
current account, that is, [ ]. 


4 FQFIL 


6 FQPPN 


26 


30 FQDEV 
32 FQDEVN 


34 


36 
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Data Returned 


FIRQB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


Errors 


NOSUCH 
PAKLCK 
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LIITITTTTI TAA 0 


M/A ATI 2 FQJOB 
PITTILLTITATALATALAA 4 

| project number 6 FQPPN 
: 
: 
: 


LITIATTIATIAT TAA | 16 
PIIIITTITTIAT TIAA I 20 
LITIITTIAT IIIT I 22 


, 
: 
: 
; 


Device is not a disk, or no match exists for the specified index. 
The disk is restricted and the caller does not have DEVICE privilege. 


3.36.36 UU.PRI (Change Priority/Run Burst/Job Size) 


Privileges Required 


TUNE is required to change any job’s priority, run burst, or size. 


Data Passed 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. . 
FIRQB+FQPPN Run priority values range from -200 to 170 in steps of 10. The 
value -200 suspends the job. 
FIRQB+FQNAM1 The run burst should be a value from 1 to 177. If you use a value 


outside this range, the monitor sets the run burst to 6. 


FIRQB+FQNAM1+2 The maximum size can range from 1 to 377 (1K-word units). The 
system uses SWAP MAX if you exceed that value. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.PRI subfunction does 
not return any meaningful data. 


Errors 


BADFUO The job number specified at FIRQB+FQFIL does not exist. 
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3.36.37 UU.PRV (Set/Clear/Read Current Privileges) 


The UU.PRV directive lets you read the current privilege mask or selectively 

set and/or clear bits in it. This function is distinct from the .SET or .CLEAR 
directives, which apply only when running a privileged program and then update 
the entire current mask at once. 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne— 
monic Offset Offset monic 
1 | LILIIITITIT ATI AT 0 
FQFUN 83 UU.PRV (= 34) LELATTII TTI 2 
5 4 FQFIL 
bits to be set in the 
7 current privilege mask 6 
(4 words) 
11 10 
13 | | 12 
15 FILEPITTITA ATI IAT Ta Td 14 
17 LILIA AIA AT 16 
21 20 FQNAM2 
bits to be cleared in the 
23 current privilege mask 22 
(4 words) 
25 24 
27 26 
31 | LILLIE TITTTTT ATTA 30 
33 TILITTIT TIT TATI AAA  A 32 
35 LIITTITITTITT AIT ATA 34 
37 LILI TITITIT IATA IA AT 36 


FIRQB+FQFIL The bits to be set in the current privilege mask. If you do not want 
to set any privileges, use four words of zero. Before setting the 
specified bits, the system performs an AND operation between the 
bits the caller passes and the caller’s authorized privilege mask 
to prevent the caller from setting unauthorized bits. Note that 
this applies even for temporary privileges. Thus, a temporarily 
privileged program can use UU.PRV to drop any single privilege, 
but it can regain only those that the caller is authorized to have. 


FIRQB+FQNAM2 The bits to be cleared in the current privilege mask. If you do not 


want to clear any privileges, use four words of zero. 
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NOTE 


If all eight words are zero, no bits are set or cleared. Thus, the job's 
privileges remain unchanged. This is the way to read your current 
privileges. 


Data Returned 


FIRQB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
5 | | i 4 FQEFIL 
7 current privilege. mask 6 
(4 words) 
11 10 
13 12 


FIRQB+FQFIL The bits set represent the privileges now in effect. 


NOTE 


A privileged program that wants to find out what privileges the user 
has needs to do a drop temporary privileges function followed by a read 
privileges function. | 


Conversely, a privileged program that wants to check whether the 
program has the right privileges should issue the read privileges 
function while temporary privileges are in effect. 
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3.36.38 UU.RAD (Read or Read-and-Reset Accounting Data) 


Privileges Required 


None required to read your own account. Set account access (GACNT or WACNT) 
is required for all other accounts, or to reset accounting data. 


Data Passed 


Mne- Octal 
monic Offset 


FIRQB 
Octal Mne— 
Offset monic 


1 TIIIIIIAA IIIA 0 
FQFUN 3 UU.RAD (= 16) Unhedeee, 2 
7 | 0 = read; <>0 = read and reset 6 FQPPN 
15 PIITIITTT IAT 14 
17 TIIITETTT AIA 16 
23 LTETTTATT III ETA 22 
25 PETTTLTTT TAT TAA TAT ET 24 
27 EITTITAT ITALIA Add] 26 
31 device name (disk) (2 ASCII characters) 30 FQDEV 
35 PLTTIATT ITT AAT AT Ta 34 
37 VALATATAT ITAL TA ATT 36 
FIRQB+FQFIL The index number of the account to read. If the index is zero, the 
directive reads the account specified in bytes 7 and 8. If the index 
is nonzero, the directives searches for an account based either on 
this index entry or on a wildcard PPN search. The value of the 
flag in FIRQB+FQNAM1+2 controls which function the directive 
does. 
FIRQB+FQPPN The reset flag. If zero, the directive only reads accounting data. 
If nonzero, the directive reads and resets accounting data. If the 
caller does have account access privilege, the system performs a 
read operation only. 
FIRQB+FQNAM1 The programmer number. If this and the project number are zero, 
the directive uses the current account. A -1 indicates a wildcard. 
FIRQB+FQNAM1+1 The project number. If this and the programmer number are zero, 
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the directive uses the current account. A -1 indicates a wildcard. 


FIRQB+FQNAM1+2 =‘ Flag byte. 


Bit 
0 


Setting 
Clear 


Set 


Clear 


Set 
Clear 


Set 


Clear 


Set 


Meaning 


Implies the call returns the number of 
blocks owned by the account. 


Implies do not return this data. Note that 
setting this bit to one can save considerable 
execution time (for Level 1.1 or older disk 
structures) if you do not need the disk usage 


information otherwise returned to the word 
at FIRQB+FQPPN. 


Means the PPN at FIRQB+FQNAM1 corre- 
sponds to a real account, if index value at 
FIRQB+FQFIL is zero. If index value is not 
zero, the system uses the index value and 
ignores any PPN at FIRQB+FQNAM1. 


Means the PPN at FIRQB+FQNAM1 con- 
tains a wildcard (377). 


Means the call returns general accounting 
information in the pre-V9.0 format. 


Means return disk quota information in the 
updated format. Disk quota information is 
not available in earlier formats. 


Means the call is a read-only lookup on the 
caller’s own PPN if the caller does not have 


GACNT or WACNT privileges. 


Means UU.RAD returns a protection vi- 
olation error if a caller tries to perform 
a restricted function without having the 
required privileges. 


.UUO—UU.RAD 3-359 


Data Returned (Bit 2 Set in FIRQB+FQNAM1+2) 


FIRQB 
Mne- Octal | Octal Mne- 
monic Offset Offset monic 
, : 
: 
FIRQB+FQPFLG Count of open files is in bits 0-9. The number of jobs is in bits 


10-15. 
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Data Returned (Bit 2 Clear in FIRQB+FQNAM1 +2) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
5 (same as data passed 4 FQFIL 
7 6 FQPPN 
11 PPN of account read 10 FQNAM1 
13 password of account read (2 words in 12 
RAD50 format) or zeros 
15 | 14. FQEXT 
17 LSB of CPU time (.1 seconds) 16 FQSIZ 
23 LSB of KCTs | 22 
FQPROT 27 MSB of CPU time MSB of KCTs 26 FQPFLG 
31 | (same as data passed) | 30 FQDEV 
33 | (same as data passed) 32 FQDEVN 
35 disk quota in blocks; 0 = unlimited 34 
37 UFD cluster size 36 

FIRQB+FQPPN If the byte at FIRQB+FQNAM1+2 in the data passed is 1, this 
word is zero. 

FIRQB+FQNAM1+2 If the caller has GACNT or WACNT privilege and the account 
allows password look-up, the password is returned as 2 words 
of RAD50. Otherwise, zeros are returned. 

FIRQB+FQSIZ The LSB of the CPU time in tenths of a second. See the byte 
at FIRQB+FQPROT for the MSB. 

FIRQB+FQMODE The LSB of the Kilo-Core-Ticks (KCTs). See the byte at 
FIRQB+FQPFLG for the MSB. 

Errors 


BADDIR The account does not have all the necessary directory structures. 
BADFUO Device specified is not a disk. 


NOSUCH _ The PPN specified does not exist on the disk, or the index specified is greater 
than the number of accounts on the disk. 


PRVIOL The caller does not have sufficient privilege to perform the indicated func- 
tion. 
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3.36.39 UU.RTS (Add/Remove/Run-Time System or Resident Library, or 
Create Dynamic Region) 


Privileges Required 


Read access (by protection code, GREAD, WREAD, and/or SYSIO privilege) is 
required to install a run-time system or resident library. INSTALL is required to 
install, remove, load, or unload a run-time system or resident library, or create a 
dynamic region. 


Data Passed—Add a Run-Time System 


FIRQB 
Mne—- Octal Octal Mne- 
monic Offset Offset monic 


mn) 


11 run-time system name 10 FQONAM1 

13 (2 words of RADS0O) 12 

15 | start load address or seth 14 FQEXT 

21 | min. user job image size, K words (P.MSIZ) 20 FQBUFL 

23 linked—list position 22 FQMODE 
FQPROT 27 dflt. exec. file type (P.DEXT), RAD50 26 FQPFLG 

31 | davies name (disk) where stored 30 FQDEV 

35 LATALPA IS TAL PALATE ELLY 34 
FIRQB+FQFIL All bits clear implies the values for PSIZE, PMSIZ, PFLAG, 


and P.DEXT symbols are in the call. Bit 7 set means the system 
should obtain the values for these symbols from the .RTS file. 


FIRQB+FQPPN The programmer number of the run-time system to install. 


FIRQB+FQFQPPN+1 The project number of the run-time system to install. If this and 
FQPPN are both zero, the default PPN is [0,1] 


FIRQB+FQNAMI1 The file name of the run-time system to install, in RAD50 format. 
The file extension must be ".RTS" and the file must be contiguous. 
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FIRQB+FQEXT The 1K word section of memory where the run-time sustem will be 


loaded. The numbering runs from 0 to n-1, where n is the number 
of 1K word sections of memory in the system. 


If the value is 0, the monitor picks the load address each time 
the run-time system is loaded from the disk. (If the /LOCK or 
/NOREAD_ ONLY bits are set, the monitor picks the load address 
once, as for the value -1.) 

If the value is -1, the monitor picks the load address once, when 


the run-time system is first installed, and loads it at that address 
each time it is used. 


The monitor takes other values as the specific address to load the 
run-time system this time. 


FIRQB+FQMODE The position in the linked list of run-time system description 


blocks at which to place the description block for this run-time 
system. 


If the value is 1, the directive places the description block immedi- 
ately after that of the primary RTS. 


If the value is nonzero and less than or equal to the number of 
blocks currently in the list, the call places this new block in that 
position following the primary RTS block. 

If the value is zero or a value greater than the number of blocks 


currently in the list, the call places this new block at the end of 
the list. 


FIRQB+FQMODE+1 _ All bits clear means the memory occupied by this run-time system 


can be released when usage count goes to zero. Bit 7 set means 
the run-time system is permanently resident and is loaded in 
memory as part of the install. 


FIRQB+FQPFLG The default extension type for the run-time system to be installed, 
in RAD50 format. 
FIRQB+FQDEV The name of the device (must be a disk) where the run-time 


system is stored. If you do not specify a name, the default is SY:. 


FIRQB+FQDEVN The unit number of the disk where the run-time system is stored. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does 
not return any meaningful data. 


Errors 


BADCNT 


DEVNES 
DTOOOF 
FIEXST 

NOBUFS 


NOROOM 


NOSUCH 


The range of memory starting at the load address at FIRQB+FQEXT is not 
available. See the output of the SHOW MEMORY command to select an 
available range of memory. 


The device was not a disk, or the disk was mounted NFS. 
The systemwide limit of open files has been reached. 
A run-time system with the same name already exists. 


Adding a run-time system description block requires a small buffer and none 
is currently available. 

If loaded at address specified, memory is fragmented and a swapping 
violation occurs. See the discussion of assigning and allocating memory in 
the RSTS/E System Installation and Update Guide for guidelines on how to 
avoid fragmenting memory. 


No file with the name given and a type of .RTS can be found in the account 
at FIRQB+FQPPN on the device specified. 
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PRVIOL The file to be added has a bad format. For example, it is not contiguous or 
has illegal entries in the SIL index. 


Data Passed—Remove a Run-Time System 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
. : 
: 
11 run—time system name 10 FQNAM1 
13 (2 words of RAD50) 12 
17 PEEATTATL IA TAAA Sd Aa abd 16 
21 LIIATTTITTTIA TTT 20 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does 
not return any meaningful data. 


Errors 


INUSE This run-time system is currently being loaded into memory or is resident | 
and in use. It cannot be removed until the usage count is zero. | 


NOSUCH The run-time system is not currently defined. 


PRVIOL The run-time system is the primary run-time system or the system default 
keyboard monitor and cannot be removed with this call. Use the DEFAULT 
initialization option to change the primary run-time system before starting 
timesharing. The system default keyboard monitor is always DCL. 
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Data Passed—Unload a Run-Time System 


Mne- Octal 
monic Offset 


FQFUN 3 


GIALILL ETAL ALT ALE 


FIRQB 


run—time system name 


(2 words of BAD 2e) 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does 
not return any meaningful data. 


Errors 


INUSE 


NOSUCH 


Octal Mne—- 
Offset monic 


4 FQFIL 


10 FQNAM1 


The run-time system is currently being loaded or is resident and in use. It 


cannot be unloaded until usage count is zero. 


The run-time system is not currently defined. 
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Data Passed—Add a Resident Library 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
| : 

FQFUN 3 UU.RTS (= -—22) 2 

11 | run—time system name 10 FQNAM1 

13 (2 words of RAD50) 12 

31 device name (disk) where stored | 30 FQDEV 


FIRQB+FQPPN The programmer number of the resident library to install. 


FIRQB+FQFQPPN+1 The project number of the resident library to install. If this and 
FQPPN are both zero, the default PPN is [0,1] 


FIRQB+FQNAM1 The file name of the resident library to install, in RAD50 format. 
The file extension must be ".LIB" and the file must be contiguous. 
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FIRQB+FQEXT 


FIRQB+FQMODE+1 


FIRQB+FQFLAG 


FIRQB+FQPROT 


The 1K word section of memory where the resident library will 

be loaded. The numbering begins at the first available 1K word 
section and ends at n-1, where n is the total number of 1K word 
sections of memory in the system. 


If the value is 0, the monitor picks the load address each time 
the resident library is loaded from the disk. The monitor picks 
the highest available address. Libraries of this kind are called 
small floating libraries. They must be entirely mapped within the 
virtual address space. They are provided for compatibility with 
older programs. This value is equivalent to the DCL qualifier 
/NOADDRESS=RESTRICTED. 


If the value is -1, the monitor picks the load address once, when 
the run-time system is first installed, and loads it at that address 
each time it is used. The monitor picks the highest available 
address. This value is equivalent to the DCL qualifier /ADDRESS. 


If the value is -2, the monitor picks a new load address each 
time the library is loaded. Libraries of this kind are called 
large floating libraries and can be larger than the virtual ad- 
dress space. This value is equivalent to the DCL qualifers 
/NOADDRESS=UNRESTRICTED or /NOADDRESS. 


The monitor takes other values as the specific address to load the 
resident library specified. Libraries of this kind are called fixed 
resident libraries. These values are equivalent to the DCL qualifer 
/ADDRESS=n. 


If the value is 0 or -2 and the /STAY or read/write bits are set, the 
monitor picks the load address once, as for the value -1. 


All bits clear means the resident library can be removed from 
memory when usage count goes to zero. Bit 7 set means the resi- 
dent library is permanently resident and is loaded into memory as 
part of the install process. 


Bit settings indicate resident library characteristics: 


Bit Setting Meaning 

9 Set The resident library is to be accessed by 
only one user. That is, the library is not to 
be shared. 

Clear The resident library can be shared by more 
than one user. 

10 Set Read/write access is allowed. 

Clear Read-only access. 

12 Set Errors occurring within code in the resident 
library are not to be recorded in the system 
error log. 

Clear Errors may be recorded in the system error 
log. 

13 Set The resident library is immediately removed 
from memory when its usage count goes to 
zero. 

Clear When the usage count for this library goes 


to zero, the monitor will remove it from 
memory when the space it takes is needed 
for something else. 


All other bits are reserved and should be zero. 


The protection code. If no code is specified, the default is 42. 
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Data Returned 


Except for a 


possible error in byte 0 of the FIRQB, the UU.RTS subfunction does 


not return any meaningful data. 


Errors 


BADCNT 


DEVNFS 
DTOOOF 
FIEXST 

NOBUFS 


NOROOM 


NOSUCH 


PRVIOL 


You did not specify a load address, or the one specified is not available. See 
the output of the SHOW MEMORY command to find an available range of 
memory. 


The device was not a disk, or the disk was mounted NFS. 
The systemwide limit of open files has been reached. 
A resident library with the specified name already exists. 


Adding a resident library description block requires a small buffer and none 
is currently available. 

If loaded at address specified, memory is fragmented and a swapping 
violation occurs. See the discussion of assigning and allocating memory in 
the RSTS/E System Installation and Update Guide for guidelines on how to 
avoid fragmenting memory. 

No file with the name given and a type of .LIB can be found for the given 
account and device. 


The file to be added has a bad format. For example, it is not contiguous or 
has illegal entries in the SIL index. 


Data Passed—Remove a Resident Library 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
(mmm | 
i anmmmnnn —_d 
11 resident library name 10 FQNAM1 
13 (2 words of RADS50) 12 
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Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does 
not return any meaningful data. 


Errors 


INUSE You tried to remove a library that is being loaded into memory or is in use. 
A resident library cannot be removed while a job is attached to it. 


NOSUCH You specified a resident library that is not currently defined. 


Data Passed—Unload a Resident Library 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
] ee 
)[ imu) 
11 resident library name 10 FQNAMT1 
13 (2 words of RAD50) 12 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does 
not return any meaningful data. 


Errors 


INUSE You tried to unload a resident library that is now being loaded or is in use. 
A library cannot be unloaded while a job is still attached to it. 


NOSUCH You specified a resident library that is not currently defined. 
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Data Passed—Create Dynamic Region 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
| . 
: . 
11 | | auaame region name | 10 FQNAM1 
13 (2 words of RAD50) 12 
15 14 FQEXT 
21 TELL Gs | 20 
23 creation flags 22 FQMODE 
25 region flags 24 FQFLAG 
FQPROT 27 26 FQPFLG 
31 30 
33 32 
35 34 
37 36 
FIRQB+FQNAM1 If zero, the monitor creates an unnamed dynamic region. 
FIRQB+FQEXT The starting address of the dynamic region is K times the value of 


this word. If zero, the monitor computes the starting address for 
the dynamic region. 


FIRQB+FQSIZ 
Bits Meaning 
0-7 Size region requested (maximum of 255) in K words of 
memory. 
14 Set to 1 if the directive can accept a smaller size region 


than requested when not enough memory exists. Set to 
0 if the directive should return an error when there is 
not enough memory to satisfy the request. 


15 Set to 1 to use bits 0-7 for size. Set to 0 to use only 
bits O—6 for size. 
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FIRQB+FQMODE 


FIRQB+FQFLAG 


FIRQB+FQPFLG 
FIRQB+FQPROT 


Creation flags. The following bits are currently defined: Bit 7, 
when set, means attach this job to the named region. Bit 15, 
when set, means do not delete this region even if all users detach 
from it; this is the /LOCK bit. All other bits are reserved and 
should be zero. 


You can create a dynamic region with or without a name. 
However, if the job shares the dynamic region with another job, 
or if the dynamic region was created with bit 15 of FQMODE 
set so that it remains in memory, it must have a name in 


FIRQB+FQNAMI1. 


Unless you have the TUNE privilege, the size of the region is 
controlled by the dynamic region limit set for the system. See the 
UU.CFG directive and the RSTS/E System Manager’s Guide. 
Region flags. The following bit is currently defined: Bit 9, when 
set, means this region cannot be shared. All other bits are re- 
served and should be zero. 

If nonzero, then the value in FIRQB+FQPROT is real. 


The protection code of the region. 


Data Returned—Create Dynamic Region 


Mne— Octal 
monic Offset 


FIRQB 
Octal Mne—- 
Offset monic 


| . 
: : 
, ) 
FIRQB+FQPPN The ID of the created dynamic region. The .PLAS directives use 
this ID. 
FIRQB+FQSIZ The size of the created dynamic region in K words. The value can 


be in the range 1 to 255. 


.WUUO—UU.RTS 3-371 


Errors 


BADCNT You tried to create a region with an illegal size specification or the load 
address was not valid. 


FIEXST You specified the name of a dynamic region or resident library that already 
exists. 


NOBUFS A small buffer was not available for the region description block. Also, if 
attachment was specified, a small buffer was not available for the window 
descriptor block. 


NOROOM If the dynamic region was loaded at the specified address, memory is 
fragmented and a swapping violation occurs. If the monitor was choosing 
the address, there is not enough free memory to create the region. 


Data Passed (Create/Delete Virtual Disk) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


iii | 


Start Virtual Disk Address | 


1 


FQFUN 3 


5 4 FQFIL 


6 FQPPN 


7 
11 
13 
15 14 FQEXT 


17 16 FQSIZ 


PIIIPIIIIIT IIIT TTT | 


21 
23 
25 
27 


31 


33 


35 


37 


FIRQB+FQFUN -22 (UU.RTS) 
FIRQB+FQFIL 32 (Create/delete virtual disk) 


FIRQB+FQEXT K word address at which to place the virtual disk (from 0 to 2043), 
or -1 to let RSTS/E select the best-fit address. 


FIRQB+FQSIZ Size of virtual disk to create, in K words (from 1 to 2044), or 0 
to delete the current virtual disk. If you specify 0, the address 
parameter in FQEXT is ignored. 
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Discussion 


This call allocates memory for the virtual disk. Any memory so allocated is 
not available for other use, nor can it be windowed or mapped using the .PLAS 
directives. When the virtual disk is deleted, the memory is then made available 


for other uses. 


When the monitor receives a request to create a virtual disk, the memory man- 
ager must sometimes "shuffle" things in memory (such as jobs and run-time 
systems) to make enough contiguous memory space for it. This task may take 
some time, particularly on very busy systems. Before the virtual disk driver 
allows the first access to the newly-created virtual disk, it ensures that all the 
memory that is supposed to be available for the virtual disk has really been allo- 
cated. If not, then the virtual disk driver returns a ?7Device hung or write locked 
error to the job requesting the access. If this happens, the requesting job should 
sleep for a few seconds and then retry the operation, thus giving the memory 
manager time to do its job. 


When a virtual disk is created, it is not automatically initialized as a RSTS/E vol- 
ume. As in the past, you must still initialize it (using the INITIALIZE command) 
and mount it (using the MOUNT command) if necessary. 


You must have HWCFG and INSTALL privileges to create or delete the virtual 


disk. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, this subfunction does not 
return any meaningful data. 


Errors 


When creating: 


PRVIOL 
NOROOM 


BADCNT 
NOBUFS 


FIEXST 


When deleting: 


PRVIOL 
INUSE 


NODEVC 


User or program did not have the HWCFG privilege. 


There was not enough contiguous memory available to create the 
virtual disk at the requested size. 


The specified size or address was invalid, or, if an address was 
given, the virtual disk would not fit at that address. 


Not enough small buffers were available to build the memory 
descriptor blocks. 


A virtual disk already exists. 


User or program did not have the HWCFG privilege. 


The virtual disk is mounted, has open files, or is open in non-file- 
structured mode. 


There is no virtual disk to delete. 
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3.36.40 UU.SLN (System Logical Names) 


Privileges Required 


INSTAL is required to add, remove, or change system logical names. 


Data Passed — Add New Name 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


. 
FQFIL+1 5 | novieelaee flag 4 FQFIL 


10 FQNAM1 
logical name in RAD50 format 12 
(5 words) 
14 
16 
20 


FIRQB+FQFIL This code adds a new entry to the list of system logical names. 

FIRQB+FQFIL+1 Set to 1 to replace an existing system logical with the new infor- 
mation. 

FIRQB+FQNAM1 The new logical name, put on the general or disk logical list 
according to the following conditions (checked in order by the 
system): 


1. Ifthe device name specified at FIRQB+FQDEV is not a disk. 

2. Ifthe device name is a disk and you specified a PPN at 
FIRQB+FQPPN. 

3. Ifthe logical name is longer than nine characters. 

4. Ifthe device name is a disk and you did not specify a PPN 
at FIRQB+FQPPN, the system checks to see if the disk is 
mounted. If the disk is not mounted, the system adds the 
logical name to the general logical list. If the disk is mounted 
and currently has no logical name assigned to it, the name is 
put on the disk logical list and assigned to that disk. All other 
cases are put on the general logical list. 
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Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.SLN subfunction does 
not return any meaningful data. 


Errors 

BADNAM No logical name was given or the name contains invalid characters. 

INUSE The logical name given duplicates one already in use and FIRQB+FQFIL = 
0. 

NOBUFS An attempt was made to extend the logical name table and there was no 
room in XBUF. 


NODEVC The device specification is illegal or is not on the system. 


Data Passed — Remove Logical Name 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
7 PITLTLTLLLTTTALLAAL TS 6 

11 | 10 FQNAM1 

13 logical name in RADS50 format 12 

15 (5 words) 14 

17 16 

21 20 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.SLN subfunction does 
not return any meaningful data. 


Errors 


BADNAM No logical name was given or the name contains invalid characters. 


NOSUCH The name given is not currently defined as a logical name. 
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Data Passed — Change Disk Logical Name 


FIRQB 
Mne- = Octal Octal Mne- 
monic Offset Offset monic 
, 
FQFUN 3 U.SLN 2 
5 4 FQFIL 
7 LIITITTIIIT ITT TTT TT 6 
11 10 FQNAM1 
13 logical name in RAD50 format 12 
15 | (5 words) 14 
17 | | 16 
21 20 
23 | 22 
25 24 
27 26 
31 30 FQDEV 


FIRQB+FQFIL This code changes the logical name associated with a disk in the 
list of disk logical names. 


FIRQB+FQNAM1 The disk logical name in RAD50 format. The name can not be 
more than nine characters. 
Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.SLN subfunction does 
not return any meaningful data. 


Errors 
BADNAM No logical name was given, or the name contains invalid characters. 
INUSE The logical name given duplicates one already in use. 


NOSUCH The disk specified is not on the system. 
NODEVC The device specified is illegally formatted or is not a disk. 
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Data Passed — List Logical Name 


Mne- 
monic 


FOQFIL 


FQPPN 


FIRQB 

Mne- Octal Octal 
monic Offset | Offset 
1 — ag IIT m i” /// i E fd i] as | 0 
FOFUN 3 | uu SLN ( 25) 2 
. 
7 | | | 6 
11 ) TILT IIT! — ] i ae mae 111 | 10 
i TTT TTA | 12 
15 TTT LTT TALLL LATA LL AA ; | 14 
21 TTL | 20 

FIRQB+FQPPN Index. An integer representing the relative position of the speci- 


fied logical name in the list of system logical names. You can list 
all logicals by repeated calls with an index value starting at zero 


and incremented by one each time. 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


project number 


logical name in RADS50 format 


6 FQPPN 


10 FQNAM1 


12 


(5 words) | 14 


| 16 


20 


22 


[devin name ASCH caress) 
| must<so | device unit number 


FIRQB+FQCLUS The value of this byte is 377 if the indexed logical is a disk and 


the disk is not mounted. 


24 


26 


30 FQDEV 


32 FQDEVN 


34 FQCLUS 


36 


Errors 


NOSUCH Index out of range. 
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3.36.41 


UU.SPL (Spooling) 


RSTS/E currently has two spooling packages: the Print/Batch Services (PBS) 
package and the OPSER-based package. When you execute the UU.SPL directive, 
the system first looks at the spooled device name field (FIRQB+FQSIZ). The 
monitor, by default, routes the request to PBS if it is running and the field is null 
or LP, or it is BA and the file type is .COM. Otherwise, the monitor routes the 
request to the OPSER-based package. 


Note that by setting a bit in FQFLAG, you can force the request to be sent to 
whichever spooling package you want. 


For requests routed to PBS, any request parameter that cannot be passed by 
UU.SPL is assigned a default value. 


Privileges Required 


File read access (by protection code, or GREAD or WREAD privilege) is required 
to queue a file. File write access (by protection code, or GWRITE or WWRITE 
privilege) is also required to queue a file with the delete option flag. DEVICE 
privilege is required if the file is on a restricted device. 


Data Passed 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset Offset monic 


: LA TAIT EET 
| UU.SPL (= -34) PLIITIATT A 


PEELTTAT EP ELLA ALL ATLA 


| project number programmer number 


wildcard file name in RAD50 format 
(2 words) 


wildcard file type in RAD50O format (1 word) 


device name to queue to (ASCII); 0 = "LPO" | 


[deve unteatog [eves nt rumbor 
| PIAS ITALY , 
ves 
(2707777277777 
seve ine whee em an 
| pee unit number eal 
SE 77000077177777 77 
[Sn 222000777777777 777 


FIRQB+FQSIZ The requested device name. Permitted values are LP, BA, and 
zero which translates to "LPO:." 


FQFUN 38 


6 FQPPN 
10 FQNAM1 


14 FQEXT 


16 FQSIZ 


20 FQBUFL 


22 FQMODE 


24 FQFLAG 


30 FQDEV 


32 FQDEVN 
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FIRQB+FQBUFL The device unit real flag. If zero, it means use the default print 


or batch queue. If nonzero, it means use the queue with the same 
name as the device name. 


FIRQB+FQFLAG You can set the following bits for PBS: 

Bit Meaning When Set 

2. Delete after spooling; same as DCL command PRINT 
/DELETE. 

5 No header; same as DCL command PRINT/NOFLAG_ 
PAGES. (Ignore for batch requests. ) 

12 Network Print/Batch request 

13 Route request to OPSER spooler 

14 Route request to PBS 


If both bits 13 and 14 are set, then the request is routed to PBS. 
If both bits are clear, then the following rules apply: 


e¢ Ifthe spooler device name is "LP" or null, or the device name 
is "BA" and the file type is .COM, then the request is routed 
to PBS if it is running; otherwise, it is routed to OPSER. 


e Ifthe spooler device name is not "LP" or null, then the request 
is routed to OPSER. 


You can set the following bits for OPSER: | 
Bit Meaning When Set | 


0 The file is spooled with FORTRAN carriage control; same 
effect as QUE/TYP:FIN. 


Restart file; same effect as QUE/RE. 

Delete file after spooling; same effect as QUE/DE. 
Binary file; same effect as QUE/BI. 

The end; same effect as QUE/END. 

No header; same effect as QUE/NH. 


aoa fF ®O NY & 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.SPL subfunction does 
not return any meaningful data. 


Errors 


DEVNES 


HNGDEV 


NOBUFS 


NODEVC 


NOROOM 


NOSUCH 
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The device specified at FIRQB+FQDEV of the call is not a file-structured 


device. 


This error is caused by a hardware condition. For example, the specified 
disk could not be accessed. 


System buffers are not currently available to store this message. This may 
be a transient condition; retry the operation. 


An attempt was made to queue a file to a device that had a unit number 
greater than seven, or the file to be queued is on an invalid device. 


The number of messages pending for the queue manager program is at its 
declared maximum. This may be a transient condition; retry the operation. 


The account specified at FIRQB+FQPPN does not exist on the device speci- 
fied, the file name or type specified at FIRQB+FQNAMI1 cannot be found. 


NOTMNT The specified disk device is not mounted. 


PAKLCK The specified disk is restricted, and the caller does not have DEVICE 
privilege. 


PRVIOL An attempt was made to queue a file to which the user did not have read 
access or to queue an executable file. 
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3.36.42 UU.STL (Stall/Unstall System) 


Privileges Required 


HWCTL is required to stall or unstall a system. 


Data Passed 


FIRQB 
Mne— Octal Octal Mne— 
monic Offset Offset monic 


FIRQB+FQFIL Zero means return the system to normal (unstalled) state. One 
means Stall; suspend all currently active jobs except for the calling 
job. 


1 0 


FQFUN 3 2 


4 FQFIL 


6 


10 


12 


14 


16 


20 


22 


24 


26 


30 


32 


34 


36 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.STL subfunction does 
not return any meaningful data. 


Errors 


BADFUO You specified unstall, but the system is not stalled. 
INUSE You tried to stall the system, but it is already stalled. 
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3.36.43 UU.SWP (Add, Remove, and List System Files) 


Privileges Required 


INSTAL is required to add or remove system files. File read access (by protection 
code, or GREAD or WREAD privilege) and file write access (by protection code, 
or GWRITE, WWRITE, and/or SYSIO privilege) is required to add system files. 
WRITNES is required to add non-file-structured swap space. 


Data Passed — Add System File 


FIRQB 
Mne—- Octal Octal Mne- 
monic Offset Offset monic 
| . 
11 for [0,1] file with type of .SYS, 10 FQNAMI1 
file name as 2 words RADS5O. If both 
13 words = 0, non—file—structured disk. 12 
31 device name (disk) (2 ASCII characters) 30 FQDEV 
FIRQB+FQFIL The possible bit settings are: 
Bit Meaning 
0 Swap file 0 
1 Swap file 1 
2 Illegal (generates an error; slot 2 is always added) 
3 Swap file 3 
4 Overlay file 
5 Error message file 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the add option of the UU.SWP 
subfunction does not return any meaningful data. 
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Errors 


BADFUO 


BADNAM 


DEVNES 
FIEXST 
INUSE 


NODEVC 
NOROOM 


NOSUCH 


NOTAVL 


NOTMNT 


PRVIOL 
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The number specified at FIRQB+FQFIL is either two or is greater than six. 
The swap file 2 must exist on the system disk and cannot be added during 
timesharing. System files to be added are defined only by the values 0, 1, 3, 
4, and 5. 

No file name is specified when an overlay, an error message, or a DECnet/E 
system file is being added, or the name specified contains nonalphanumeric 
characters. 


The device specified is not a disk device. 
The system file being added is already installed on the system. 


A swap file is being added to a non-file-structured disk, but the disk is 
currently mounted (that is, it is being used as a file-structured device). 
The device specified is a disk but is not on this system. 

If an overlay or error file is being added, this error indicates that the file 
is not long enough. (The overlay file should be at least 128. blocks and 
the error file at least 16. blocks.) If a swap file is being added to a file- 
structured device, this error means that the file is not long enough to store 
even one job. 

A system file is being added to a file-structured disk, but the file with the 
name specified and with a .SYS file type does not exist in account [0,1]. 

A swap file is being added to a non-file-structured disk, but either the disk 
unit or its controller has been disabled. The system manager must use an 
initialization option to enable the unit or its controller. 

A system file is being added to a file-structured disk but that disk is not 
currently mounted. Use the MOUNT command to logically mount the disk 
before the file is added. 

A system file is being added to a file-structured disk. Either the unit is 
logically write locked, or the file specified is bad; that is, it is not contiguous 
or is currently open. 


Data Passed — Remove System File 


FIRQB+FQFIL 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
(mind 
(nd 


The possible bit settings are: 
Bit 


ao fF OO NY KF O&O 


Meaning 
Swap file 0 
Swap file 1 


Illegal (generates an error; slot 2 is never removed) 


Swap file 3 
Overlay file 


Error message file 
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Data Returned 


FIRQB_0 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 


[wrercoreore 
LATAATILATALFELA A TTT | 
mn | 


Error code or zero. 


34 FQCLUS 


FIRQB+FQCLUS Zero means the system file was successfully removed; minus one 


Errors 


BADFUO 


INUSE 


PRVIOL 
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means the system file was not found and so could not be removed. 
(If bit 4 = 1, the overlay file is removed.) 


The number specified at FIRQB+FQFIL is either two or greater than six. 
The swap file 2 must exist on the system disk and cannot be removed during 


time sharing. System files to be removed are defined only by the values 0, 
1, 3, 4, and 5. 


The swap file to be removed can be properly removed but currently contains 
one or more swapped out jobs. The system locks the file and begins swap- 
ping jobs to other files. Retry the call at a later time when the swapped out 
jobs are no longer in this file. 


A swap file is to be removed but its removal decreases the swap file space 
below the limit required to store the maximum number of jobs on the sys- 
tem. To remove the swap file, decrease the number of logins currently 
allowed (by either the SET LOGINS command or SYS call), wait until the 
number of logged in jobs falls to the maximum, and try the removal oper- 
ation again. This error also occurs if you attempt to remove the DECnet/E 
system file when DECnet/E is still on. 


Data Passed — List System File 


FIRQB 
Mne— Octal Octal 
monic Offset Offset 
| . 

FIRQB+FQFIL The possible bit settings are: 

Bit Meaning 

0 Swap file 0 

1 Swap file 1 

2 Swap file 2 

3 Swap file 3 

4 Overlay file 

5 Error message file 

6 DECnet/E system file 


Mne— 
monic 


FQFIL 
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Data Returned — List System File 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, : 
: : 
: ; 
11 file name in RAD50 format | 10 FQNAM1 
(2 words) 
13 12 
33 <>0, unit number real 32 FQDEVN 
Errors 


BADFUO The number specified at FIRQB+FQFIL is less than zero or greater than 
S1X. 


NOSUCH The number specified at FIRQB+FQFIL refers to a file that is not currently 
installed. 
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3.36.44 UU.SYS (Return Job Status Information) 


Privileges Required 


JOBCTL is required to read the status of another job, except a job running on a 
pseudo keyboard controlled by the caller. TUNE is required to obtain priority or 
run burst status. — | 


Data Passed 


FIRQB 
Mne— Octal Octal Mne— 
monic Offset Offset monic 


Cae 
oma PITT 
a1] EITAAAALTILATILLLLLA 30 
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Data Returned (for subcode = 0) 


FIRQB | 
Mne— Octal Octal Mne—- 
monic Offset Offset monic 


. ; 
Vee 2 FQJOB 
FQSIZM 5 jebie console KB no. 4 FQEFIL 
swap slot eealina - 6 FQPPN 
15 | 7 LSB of KCTs | 14 FQEXT 


Ni G 


23 job name in RADS50 format 22 FQMODE 
(2 words) 
25 | 24 
31 job keyboard monitor in RAD50 format 30 FQDEV 
(2 words) 
33 32 
35 current run-time system in RAD50 format 34 FQCLUS 
(2 words) 
37 36 
FIRQB+FQSIZM If this value is negative, the job is detached, and the value is the 


one’s complement of the keyboard number to which the job was 
previously attached. 


FIRQB+FQPPN Returned only if job is attached to a pseudo keyboard. 
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Data Returned (for subcode = 1) 


FIRQB 
Mne- Octal Octal Mne- 
monic Oliset Offset monic 
| rin | 


FIRQB+FQSIZM If this value is negative, the job is detached, and the value is the 
one’s complement of the keyboard number to which the job was 
previously attached. 


FIRQB+FQMODE Returned only if the caller has TUNE privilege. 
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Data Returned (for subcode = 2) 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
, . 
: caling eb no? | 2 FONOE 
7 |job’s current D-space 6 FQPPN 
11 10 FQNAM1 
13 job’s current privilege mask 12 
15 (4 words) 14 FQEXT 
17 | | 16 FQSIZ 
23 22 
reserved 
25 24 
27 job’s PPN 26 FQPFLG 
31 30 FQDEV 
33 job’s saved privilege mask 32 
35 | (4 words) 34 
37 | 36 
FIRQB+FQSIZM If this value is negative, the job is detached, and the value is the 
one’s complement of the keyboard number to which the job was 
previously attached. 
FIRQB+FQPPN The monitor returns the job’s current I-Space size in FIRQB+FQPPN 
and the job’s current D-Space size in FIRQB+FQPPN+1. 
FIRQB+FQNAM1 The monitor returns the job’s current privilege mask in four words 
beginning at FIRQB+FQNAM1. 
FIRQB+FQBUFL The monitor returns the job’s access type in this byte. The follow- 
ing values are defined: 
Value Meaning 
0 Local 
1 Dial-up 
2 Batch 
4 Network (SET HOST) 
6 Network server 
All other values are reserved. 
FQBUFL+1 The monitor returns the job’s header size in FIRQB+FQBUFL+1. 
FIRQB+FQPFLG The monitor returns the PPN of the job in the word beginning at 
FQPFLG. 
FIRQB+FQDEV The monitor returns the job’s saved privilege mask in the four 


words beginning at FIRQB+FQDEV. This differs from the current 
privilege mask if the job has temporary privileges. 
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Errors 


BADFUO The job number specified at FIRQB+FQFIL is less than zero or greater than 
JOB MAX. | 


PRVIOL The job specified at FIRQB+FQFIL does not exist. 
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3.36.45 UU.TB1 (Get Monitor Tables, Part 1) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset Offset monic 
[mn +d 
sf mn | 
[mn de 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset OMset monic 
, : 
11 | (DEVPTR) address of pointers to dev. DDBs 10 FQNAM1 
13 /(MEMLST) root link word in 1st mem ctl sbik | 12 


FIRQB+FQCLUS System internal format for date is: 
[(year - 1970) * 1000.] + day-within-year 


Errors 
No errors are possible with UU.TB1. 
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3.36.46 UU.TB2 (Get Monitor Tables, Part Il) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne—- Octal Octal Mne- 
monic Offset Offset monic 


LLITITITTATAT ATTA TT 


UU.TB2 (= -14) PTTITT TTT 


LTIIITITTTTAT TATA ATT TL | 


1 


FQFUN 3 


5 


LITT TS 


LIITTITIITTT TTT ATT TT 


7 


11 


13 


15 


17 


a) 


23 


25 


27 


31 


33 


35 


37 
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Data Returned 


FIRQB 
Mne— Octal Octal Mne— 
monic Offset Offset monic 


D_rerrerninnennnn 
7 (FREES) sade of free buffer info able | 


2 FQJOB 


4 FQFIL 
6 FQPPN 


10 FQNAM1 


TTYHCT) no. hung term errs since startup 
(JOBCNT) no. jobs now / no. logins allowed 


(RTSLST) rt. Ink.word in RTS dsc.blk.list 


ERLCTL) error logging control data | 


14. FQEXT 
16 FQSIZ 


20 FQBUFL 
22 FQMODE 


24 FQFLAG 


26 FQPFLG 


( ) | 
| (MEMSIZ) physical iaaeneny size, K-words*32 


30 FQDEV 
32 FQDEVN 


34 FQCLUS 


36 FQNENT 


Errors 
No errors are possible with UU.TB2. 
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3.36.47 UU.TB3 (Get Monitor Tables, Part Ill) 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- = Octal Octal Mne- 
monic Offset Offset monic 


UU.TB3 (= —29) Tf IIlitsli 


1 


FQFUN 3 


5 


7 


11 
13 
15 


17 


21 


23 
25 
27 
31 
33 
35 : 


37 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
| . 
17 | (MAGLBL) saa of mag tape labeling detault | 16 FQSIZ 
25 | (EMLCTL) EMT logger control table ‘| 24 FQFLAG 
27 | paraweie configuration word | 26 FQPFLG 
FIRQB+FQPFLG Flag word bit settings indicate hardware configuration attributes: 
Bit Setting Meaning 
3 Clear FIS not available 
Set FIS available 
5 Clear Unibus system 
Set QBUS system 
9 Clear FPP not available 
Set FPP available 
10 Clear CIS not available 
Set CIS available 
13 Clear System does not have I&D Space 
Set System has I&D Space 
FIRQB+FQNENT The Memory Management Unit (MMU) value for the disk statis- 


tics table, if unsupported disk statistics are turned on. 


Errors 
No errors are possible with UU.TB3. 
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3.36.48 UU.TRM (Set Terminal Characteristics) 


Privileges Required 


HWCEFG is required to set a terminal other than the caller’s own, or to set 
permanent characteristics. A job owns a terminal if the terminal is the job’s 
console terminal, or if the terminal is opened or allocated by the job. 


Data Passed (subfunction= 0) 


FIRQB 
Mne- Octal | Octal Mne- 
monic Offset Offset monic 


1 PITITITTTTITATT TTT 0 


FQFUN' 3 UU.TRM (= 20) I/II 2 
asizm 5 | 877(curent) or KB no 4 FOFIL 


7 200(tab)/377(no tab) width: 0 or width+1 6 FQPPN 
11 200(lwe een.) 200(no frm)/377(form) 10 FQNAM1 
15 200(no)/377(lwe in) 200(no scp)/377( scp) 14 FQEXT 
21 xmt baud rate PARITY: 1(no)2(e)3(od 20 FQBUFL 
23 200(4)/377(no * 200(no stl)/377(stl) 22 FQMODE 


FQPROT 27 200(no)/377(esc seq) PERMANENT flag 26 FQPFLG 
31 | 200(ne os0y/877 (050) 80 FODEV 
33 RSUM;200(4C)/377(any) 200(no *RIST7(*R) 32 FQDEVN 


35 200(no GAG)/377(GAG) BRAK;200(nul)/377(4C) | 34 FQCLUS 


37 LILIIIIITTT TAIT TTT 36 


FIRQB+FQEXT Setting No Scope automatically sets No Stall. Setting Scope 
automatically sets Stall. 
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FIRQB+FQSIZ+1 


FIRQB+FQBUFL 


FIRQB+FQBUFL+1 


Receiver baud rate is set as follows: 
0 No change 


n The internal code to determine the baud rate 
at which the terminal receives characters. If 
FIRQB+FQBUFL+1 is zero, this code also determines 
the transmit (output) baud rate. (Requires HWCTL 
privilege.) Note that you can set internal codes only for 
DH11, DZ11/DZV11, and DHU11/DHV11 interface lines 


as follows: 
DHi1 DZ11/DZV11 $DHUi1/DHV11 

Code Speed Code Speed Code Speed 

1 0 1 0 1 0 

2 50 2 50 2 75 

3 75 3 75 3 110 

4 110 4 110 4. 134.5 

5 134.5 5 134.5 5 150 

6 150 6 150 6 300 

7 200 7 300 7 600 

8 300 8 600 8 1200 

9 600 9 1200 9 1800 
10 1200. 10 1800 10 2000 
11 1800 11 2000 11 2400 
12 2400 12 2400 12 4800 
13 4800 13 3600 13 Res 
14 9600 14 4800 14 9600 
15 EXTA 15 7200 15 19200 
16 EXTB 16 9600 
Parity and 8-bit mode values: 
1 No parity 
2 Even parity 
3 Odd parity 
4 Enable parity characteristic 
20 8-bit characteristic off 
30 8-bit characteristic on 
Transmitter baud rate is set as follows: 
0 Both the receive (input) and transmit (output) speeds 

are determined by the value n in FIRQB+FQSIZ+1. 

n The internal code to determine the baud rate at which 


the terminal transmits characters when a split speed 
setting is used. (HWCTL privilege required.) You can 
use split speed settings only with the DH11, DHU11, 
and DHVI11 interface lines. 
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FIRQB+FQFLAG+1 Value=10+DATA+STOP+PARITY 


where: 


DATA is 0 for 5-bit characters 
1 for 6-bit characters 
2 for 7-bit characters 
3 for 8-bit characters 


STOP is 0 for 1 stop bit per character 
4 for 2 stop bits per character 
or 1.5 bits if DATA = 0 


PARITY is 0 for no parity bit 
20 for even parity format 
60 for odd parity format 


This byte applies only to interfaces that support DATA/STOP/PARITY 
features. When this byte is used with these interfaces, it over- 

rides the setting of FIRQB+FQBUEL. In addition, when this 

byte is used, FIRQB+FQSIZ+1 (receiver baud rate) must be 


nonzero. 
FIRQB+FQPFLG The PERMANENT flag is as follows: 
0 No change 
200 Return permanent characteristics 
377 Set permanent characteristics 
FIRQB+FQDEV Determines the use of private delimiters as follows: 
0 No change. 
200 Disable (clear) the private delimiter. 
200+n Set the private delimiter to ASCII code n (in the 


range 1 to 127). If the character has a special 
meaning (for example, horizontal tab or the Ctr1/Z 
combination), the private delimiter usage has 
higher precedence. 
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Data Returned (Current Keyboard Characteristics) 


FIRQB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 


1 

3 

FQSIZM 5 
7 

11 

13 

15 

17 

21 

23 

25 
FQPROT 27 
31 

33 

35 


37 


| current job no. * 2 i 
[asstcreny Kno | KO ave | 
ee 
ee 
rece bevate [non 


2 FQJOB 
4 FQFIL 
6 FQPPN 


10 FQNAM1 


14 FQEXT 
16 FQSIZ 


20 FQBUFL 


[eam usate | no petvaveneas 
[eer | eterna | 
[nese ease og | PERMANENT os | 
[essa onset | BREAK OTRLS 


LI IIIT 8—bit characteristics 


24 FQFLAG 
26 FQPFLG 
30 FQDEV 

32 FQDEVN 
34 FQCLUS 
36 FQNENT 


FIRQB+FQFIL Bit 0 when set means the keyboard is disabled or is a pseudo 


Errors 


BADFUO 


NOTAVL 


keyboard that is not in use. 


When bits 1-6 are clear, it means no job owns the keyboard. 
Otherwise, the value in bits 1-6 is equal to the job number times 
two of the job that owns keyboard. 


Bit 7 when set means the modem line is hung up or is a pseudo 
keyboard that is not in use. 


The system returns this error for one of two possibilities: 


¢ Keyboard number is out of range of valid numbers. 
e Current keyboard is specified but is detached. 


The system returns this error if you attempt to set or retrieve information 
on a terminal that is not available, for example a terminal that has been 


disabled by INIT.SYS. 
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PRVIOL 


You do not have HWCFG privilege and tried to either: 


e Read the characteristics of a terminal not opened or assigned to your 
job. 

e Change the characteristics of a terminal other than your job’s console 
terminal (KB:). 

e Change the speed setting for your terminal. (FIRQB+FQSIZ+1 or 
FIRQB+FQBUFL+1 is nonzero.) 

e Set the permanent characteristics for a dial-up terminal, pseudo key- 
board, or local terminal. (FIRQB+FQPFLG is nonzero.) 


Data Passed (Subfunction = 1) 


Mne- 
monic 


FQFUN 
FQSIZM 


FQFLAG+1 25 
FQPROT 27 
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FIRQB 
Octal Octal Mne- 
Offset Offset monic 
; 
3 [_Uu.TAM (=20) : 
11 10 
13 12 
15 14 
17 16 
21 20 
23 22 
24 FQFLAG 
26 FQPFLG 
31 | 30 FQDEV 
33 32 FQDEVN 
35 34 FQCLUS 
37 TIIIITIITITI IIT ITT 36 


FIRQB+FQPPN 
Code Type 

0 no change 
1 Unknown 
2 LA36 

3 VT52 

4. VT55 

5 LA180S 
6 VT100 
7 LA120 
8 LA12 

9 LA100 
10 LA34 

11 LA38 
12 LA50 
13 VT101 
14 VT102 
15 VT125 
FIRQB+FQFLAG 
FIRQB+FQFLAG+1 
FIRQB+FQPFLG 


Terminal type codes. The following decimal values are valid; zero 


causes no change to occur: 


The Set characteristics flag is as follows: 


0 

1 

2 

4 
10 
200 


Code Type Code Type 

16 VT131 32 KSR33 
17 VT132 33 ASR35 
18 VT220 34 KSR35 
19 VT240 35 LNO3 

20 VT241 36-43 Reserved 
21 VT105 44 LA210 
22 VK100 45 LQPO03 
23 RT02 46 LQP02 
24 LA30 AT LA75 

25 VT50 48 VT330 
26 VT50H 49 VT340 
27 VTO05 50 VT320 
28 VTO5B 51 LA324 
29 LA30S 52-128 Reserved 
30 2741 129-255 Customer definable 
31 ASR33 


No change 


Allow operator messages 


Allow operator requests 


Allow line editing 


Allow command recall 


Insert edit mode 


The Clear characteristics flag is as follows: 


0 

1 

2 

4, 
10 
200 


No change 


Disable operator messages 


Disable operator requests 


Disable line editing 


Disable command recall 


Overstrike edit mode 


The PERMANENT flag is as follows: 


0 
200 
377 


No change 
Return permanent characteristics 
Set permanent characteristics 
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FIRQB+FQPROT 


FIRQB+FQDEV 


FIRQB+FQDEV+1 


FIRQB+FQDEVN 
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The terminal’s input buffer quota is as follows: 


0 No change 
6 The maximum number of input buffers. The default 
to value is 6. There are 28 characters per buffer. The 


255 /BUFFER_QUOTA qualifier of the SET TERMINAL 
command sets this characteristic. Users need HWCFG 
privilege to use this feature. 


NOTE 


There is no guarantee that a 
terminal can allocate its full buffer 
quota. 


Excessive use of this feature to 
allocate large amounts of buffers 
to several terminals could create a 
shortage of small buffers. 


Setting control character functions or auto-baud. The bits cur- 
rently defined are: 


0 Set Ctrl/C 
1 Set Ctrl/T 
2 Set Ctrl/R 
3 Set Ctrl/X 
4 Set autobaud 


Bits can be combined; that is one or more bits can be set at any 
time. If no bits are set, then the current setting is unchanged. All 
other bits are reserved and should be zero. 


Clearing control character functions or auto-baud. The bits cur- 
rently defined are: 


0 Clear Ctrl/C 
1 Clear Ctrl/T 
2 Clear Ctrl/R 
3 Clear Ctrl/X 
4 


Clear autobaud 


Bits can be combined; that is one or more bits can be cleared 
at any time. If no bits are cleared, then the current setting is 
unchanged. All other bits are reserved and should be zero. 


Set terminal capability flags. The following bits are currently 
defined: 

Set ANSI escape sequences 

Set advanced video 

Set width to 132 columns 

Set printer port 

Set ReGIS graphics 

Set SIXEL graphics 

Set Katakana character set 

Set selectively erasable characters 

Set dynamically redefinable character sets (DRCS) 
Set user defined keys (UDKs) 

10 Set local copy 

11 Set Non-Interactive 

12 Set Answerback mode 


If no bits are set, the current capability status is unchanged. All 
other bits are reserved and should be zero. 


Omonrnwitirh WON Ee © 


FIRQB+FQCLUS Clear terminal capability flags. The following bits are currently 
defined: 


Clear ANSI escape sequences 
Clear advanced video 
Clear 132 column flag 
Clear printer port 
Clear ReGIS graphics 
Clear SIXEL graphics 
Clear Katakana character set 
Clear selectively erasable characters 
Clear dynamically redefinable character set (DRCS) 
Clear user defined keys (UDKs) 
0 Clear local copy 
1 Clear Non-Interactive 
2 Clear Answerback mode 


meme OOoOnN Ooa»rwnd eH © 


If no bits are set, the current capability status is unchanged. All 
other bits are reserved and should be zero. 


Data Returned (Current Terminal Characteristics) 


FIRQB 
Mne— Octal | Octal Mne- 
monic Offset Offset monic 
nnn id 
S| | 
‘(mn —_*d 


Errors 


BADFUO The system returns this error for one of three possibilities: 


e Keyboard number is out of range of valid numbers. 
e Current keyboard is specified but is detached. 
e The terminal’s input buffer quota is out of range. 


.UUO—UU.TRM 3-407 


PRVIOL 


3-408 .UUO—UU.TRM 


You do not have the required privileges and you tried to either: 


e Read the characteristics of a terminal not opened or assigned to your 
job. 

e Change the characteristics of a terminal other than your job’s console 
terminal (KB:). 

e Change the speed setting for your terminal. (FIRQB+FQSIZ+1 or 
FIRQB+FQBUFL+1 is nonzero.) 


e Set the permanent characteristics for a dial-up terminal, pseudo key- 
board, or local terminal. (FIRQB+FQPFLG is nonzero.) 


e Change the terminal’s input buffer quota. 


3.36.49 UU.YLG (Enable Logins) 


Privileges Required 


SWCTL is required to enable logins. 


Data Passed 


FIRQB 
Mne-— Octal Octal Mne- 
monic Offset Offset monic 
[nnn] 
mmm _| + 
[in| 
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Data Returned 


FIRQB 
Mne- Octal Octal Mne- 
monic Oise Offset monic 
| a 
|_| 


Errors 
No errors are possible with UU.YLG. 
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3.36.50 UU.ZER (Zero Device) 


Privileges Required 


DEVICE is required to access a restricted device. Create/rename access (matching 
PPN, or GWRITE, WWRITE and/or SYSIO privilege) required to zero an account 
other than caller’s. Set account access (GACNT or WACNT privilege) is required 

to deallocate the UFD when zeroing an account. 


Data Passed 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset | Offset monic 
, . 
7 | igiset auRnbe: 6 FQPPN 
11.| volume ID for label in RADS0 format | 10 FQNAM1 
(2 words) 
13 (ANSI format mag tape only) 12 
15 PIITTTITTTTTTALLALAL | 14 
31 deviGs name (disk, fiactaee: or DECtape) | 30 FQDEV 


FIRQB+FQFIL Zero means delete all files except those write-protected against 
owner; retain UFD clusters. 


Minus one means delete all files regardless of protection code; 
release UFD clusters (users with GACNT or WACNT privilege 
only). Users without GACNT or WACNT privileges can use this 
flag to delete all files regardless of their protection codes, but 
cannot release UFD clusters. 


FIRQB+FQPPN Users without GACNT or WACNT privilege can specify the cur- 
rent account only. Be sure to include the PPN; the system returns 
an error if both bytes are zero. 


Data Returned 


Except for a possible error in byte 0 of the FIRQB, the UU.ZER subfunction does 
not return any meaningful data. 
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Errors 


BADFUO 
BADNAM 


DEVNES 
NODEVC 
NOSUCH 
NOTAVL 


PRVIOL 
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No PPN was specified. 


The specified device is ANSI magnetic tape, and the volume ID is either 
missing or invalid. 


The specified device does not allow access by file name. 

The device specified is not on the system. 

The account specified does not exist on the device specified. 

The device specified exists on the system, but you cannot zero it for one of 


the following reasons: 


e A file is currently open on the device. 

e The device is currently reserved by another job. 

e The device or its controller is disabled. 

The unit is write-locked, the unit is restricted and the caller does not have 


DEVICE privilege, or the caller does not have accounting privileges and 
FIRQB+FQPPN contains a PPN other than the current account. 


3.36.51 UU.3PP (Third-Party Privilege Checking) 


The UU.3PP directive enables or disables third-party privilege checking. This 
directive is for the use of server programs that run as a separate job; for example, 
spoolers. 


Once issued, the directive remains in effect until cancelled by another UU.3PP 
with zero in FIRQB+FQPPN, or by exit from the calling program. While in effect, 
every privilege check done by the monitor is made twice: once for the job’s PPN 
and privilege mask, and once for the PPN and privilege mask specified in the call. 
The function proceeds only when the check passes in both cases. 


Privileges Required 


None 


Data Passed 


FIRQB 
Mne- Octal Octal Mne— 
monic Offset Offset monic 


privilege mask 
(4 words) 


FQFUN 3 


6 FQPPN 


10 FQNAM1 


erin 


FIRQB+FQPPN Specify zero to cancel third-party privilege checking. 


Data Returned 


None 


Errors 


NOBUFS No small buffers available. 
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3.37 .WRITA — Write Data to File or Device (Asynchronously) 


3-414 .WRITA 


Form 
.WRITA 


Function 


The asynchronous write directive (.WRITA) performs the same basic functions 
as the synchronous write directive (.WRITE): both move data between a device 
and a user program. The difference lies in the completion of the request. While 
synchronous write requests stall the job’s execution until the request completes, 
asynchronous write requests do not stall; the program continues to run while the 
I/O request completes in parallel with program execution. The mechanism that 
the RSTS operating system uses to notify the user job upon I/O completion is an 
asynchronous completion routine. 


The .WRITA directive writes a specified number of bytes of data from a user 
buffer (defined in the XRB) to a file or device currently open on a channel. Unless 
an error occurs, the .WRITA always transfers the number of bytes specified. | 
The number of bytes specified must be less than or equal to the size of the buffer. 
Table 3—11 gives specific details for each device (see the discussion for the .WRITE 
directive). For comparison, Table 3-11 also shows the "best guess" buffer sizes 
returned by the monitor at FIRQB+FQBUFL when the file or device is opened. 


When you do I/O to or from a resident library mapped in D-Space, such as a 
dynamic region, you can use I/O buffer sizes larger than the greatest size that 
can be mapped into the program’s virtual address space. You can get single I/O 
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use 
such large block sizes. 


You only need to map the first word of the I/O buffer into the the virtual address 
space, so the monitor can locate the buffer in the resident library. However, the 
entire buffer must reside in the resident library; otherwise, the monitor rejects 
the I/O request. This feature is available only for resident libraries mapped in 
D-Space. 


Privileges Required 


EXQTA is required to write in excess of disk quota. TUNE is required for multi- 
ple asynchronous I/O requests. 


Data Passed 


FIRQB 


Mne— Octal Octal Mne- 
monic Offset Offset monic 


FERALTTAA IT ELAITAT EL EL Ta 


4 FQFIL 
6 FQPPN 


FIRQB+FQFIL The address in the user job where program flow should begin 


when the asynchronous write completes. 


If this value is zero, no AST completion is executed. In this event, 
it is understood that the user is using some other mechanism to 
determine whether the I/O successfully completed. 


FIRQB+FQPPN The user job uses this field to communicate information to the 
AST completion routine. If FIRQB+FQFIL is zero, this value is 


ignored. 
XRB 
Mne— Octal Octal 
monic Offset Offset 
[eran arouputboterinoyes do 
2 [| runtoratoyesiobewinen +d 
s[____swrnoadsossoroutr id 


Mne— 
monic 


XRLEN 
XRBC 
XRLOC 
XRCI 


XRBLK 


XRMOD 


.WRITA 
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XRB+XRLEN 


XRB+XRBC 


XRB+XRLOC 


XRB+XRCI 


XRB+XRBLKM 


XRB+XRBLK 


XRB+XRMOD 


Length of the output buffer, in bytes. The value of this word must 
be nonzero. 


The number of bytes to be written. The value of this word must 
be nonzero and less than or equal to the buffer size, as specified at 


offset XRB+XRLEN. For disk, this must be a multiple of 512. 


Starting address of the output buffer. For disk, flexible diskette, 
and magnetic tape devices, this address must be on a word (even) 
boundary. For all other devices, the buffer can begin on an odd 
address. (See the section "XRB (Transfer Request Block)" in 
Chapter 2 for more information. ) 


Channel number times two; defines the channel on which the 
data is to be written, as previously defined in an open (OPNFQ, 
CREFQ, CRTFQ, CRBFQ functions of CALFIP). 


For disk files, this byte contains the most significant bits of the 
starting block number where the write is to begin. This byte is 
combined with the word at XRB+XRBLK to form a 24-bit field. 


Starting block number where the write is to begin. Performs 

the same action as the BLOCK option for disk or the RECORD 
option for flexible diskette and non-file-structured DECtape (see 
the RSTS/E Programming Manual). This parameter is ignored if 
the device is not a random-access device. If the device is random- 
access, and this field is nonzero, it is interpreted as the block 
number where the write is to start (1 to n, where n is the length 
of the file in 512-byte blocks). If zero, the next sequential block is 
written. For disk devices opened as non-file-structured in cluster 
mode, this value is the starting device cluster number where the 
write is to begin. 

Output operation modifier; significant only for line printer, ter- 
minal, and DMC/DMR devices. (The monitor informs you with 
the FLGMOD bit of the flag word whether or not the device ac- 
cepts modifiers.) This parameter performs the same action as 
the BASIC-PLUS RECORD modifier for these devices (see the 
RSTS/E Programming Manual), 


Data Returned to Completion Routine 


FIRQB 
Mne— Octal Octal Mne- 
monic Offset Offset monic 


1 EPITALEL AE error code 0 
smn ids 
XRB 
Mne- Octal Octal Mne— 
monic Offset Offset monic 
1 PEVAPLAALITL IEE TT ALA 0 


s[ mn dt 
XRBLKM 7 MSB of block number 6 


XRB+XRBC The number of bytes not written in this .WRITE operation. This 
value is usually zero. 
XRB+XRBLKM For disk files, the MSB of the block number of the block just 


written. (Combined with XRB+XRBLK to form a 24-bit field.) 
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XRB+XRBLK 


Errors 


BADCNT 
BSERR 


HOF 


INUSE 


NOBUFS 
NOTOPN 
PRVIOL 


For random-access devices, this word contains the block number of 
the block just written. Block numbers range from 1 to n, where n 
is the length of the file, in 512-byte blocks. They define the order 
in which the file is written. For disk devices opened as non-file- 
structured in cluster mode, this is the device cluster number of 
the cluster just written. 


The completion routine address is invalid or odd. 


The specified channel number is illegal; that is, it is not in the range 0 - 36 
(since channel is specified as channel * 2), or it is an odd number. 


A write was attempted to a block beyond the end of the disk when the disk 
was opened non-file structured. 


Too much outstanding I/O for the job or the job does not have the TUNE 
privilege and has asynchronous J/O already outstanding. 

No small buffers were available for the request. 

No device is currently open on the specified channel. 


One of the following occurred: 


e The file or device currently open on the specified channel is read-only. 

e The open for this file or device did not specify write access. A write was 
requested that would extend a UFD or a contiguous file. 

e A write was attempted that would extend a file in special update mode 
and block 0 was not locked. 


e A write was attempted that would extend an executable file, increasing 
its size to more than 65,535 blocks. 


All other errors are device-dependent. Common errors are: 


DATERR 
HNGDEV 


NOROOM 


Example 


Some data error occurred. This error is issued when a parity error occurs, 
and so forth. 


Some hard device I/O error occurred. For example, the specified device is 
off-line, is physically write-locked, and so forth. 


No more room is available on the device. For example, the end-of-tape 
marker has been encountered, no more available disk space, and so forth. 


See the description of .READA for an example using .WRITA. 


3.98 .WRITE — Write Data to File or Device 


Form 
WRITE 


Function 


The .WRITE directive writes a specified number of bytes of data from a user 
buffer (defined in the XRB) to a file or device currently open on a channel. Unless 
an error occurs, the .WRITE always transfers the number of bytes specified. The 
number of bytes specified must be less than or equal to the size of the buffer. 
Table 3-11 gives specific details for each device. For comparison, Table 3—11 also 
shows the best guess buffer sizes returned by the monitor at FIRQB+FQBUFL 
when the device is opened. 


When you do I/O to or from a resident library mapped in D-Space, such as a- 
dynamic region, you can use I/O buffer sizes larger than the greatest size that 
can be mapped into the program’s virtual address space. You can get single I/O 
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use 
such large block sizes. | 


You only need to map the first word of the I/O buffer into the the virtual address 
space, so the monitor can locate the buffer in the resident library. However, the 
entire buffer must reside in the resident library; otherwise, the monitor rejects 
the I/O request. This feature is available only for resident libraries mapped in 
D-Space. 


Table 3-11: Data Output with .WRITE 


Block "Best Guess," 

Size,Bytes Bytes Restrictions on Number of Bytes 
Device (Decimal) (Decimal) Written 

Byte-Oriented Devices (FLGFRC=1, FLGRND=0) 

Keyboard (Terminal) N/A 128 None 
Pseudo Keyboard N/A 128 None 
Paper Tape Punch N/A 128 None 
Line Printer N/A 128 None 


Block-Sequential Devices (FLGFRC=0, FLGRND=1) 


Magnetic Tape 14 to 32,767 512 14 to 32,767 bytes 

DECtape (file- 510 510 Must be < 510 bytes; if < 510, automati- 
structured) cally filled with NULLs to 510 bytes. 
DMC/DMR 1 to 8000 512 None 


Block-Random Devices (FLGFRC=0, FLGRND=0) 


Disk 14 to 32,767 512 Must be multiple of 512 bytes. (Must be 
512 if writing UFD.) 

Flexible Diskette T 512 If not a multiple of block/sector size, zero 

(RX0O1 and RX02) fill to end of block/sector. 


1512 (block mode) or 128 (RX01 or RX02 single-density sector mode) or 256 (RX02 double-density sector mode) 


(continued on next page) 
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Table 3—11 (Cont.): Data Output with .WRITE 


Block "Best Guess," 

Size,Bytes Bytes Restrictions on Number of Bytes 
Device (Decimal) (Decimal) Written 

Block-Random Devices (FLGFRC=0, FLGRND=0) 
DECtape (non-file- 512 512 Must be < 512 bytes; if < 512, automati- 
structured) cally filled with NULLs to 512 bytes. 


Privileges Required 


EXQTA is required to write in excess of disk quota. 


Data Passed 


XRB 
Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 length of output buffer, in bytes 0 XRLEN 
3 number of bytes to be written 2 XRBC 
5 starting address of buffer 4 XRLOC 
XRBLKM 7 MSB of block number 6 XRCI 
11 LSB of block number 10 XRBLK 
13 VEL UCELTELIALL ALIA La PF 12 
15 optional modifier 14 XRMOD 
XRB+XRLEN Length of the output buffer, in bytes. The value of this word must 
be nonzero. 
XRB+XRBC The number of bytes to be written. The value of this word must 
be nonzero and less than or equal to the buffer size, as specified at 
offset XRB+XRLEN. For disk, this must be some multiple of 512. 
XRB+XRLOC Starting address of the output buffer. For disk, flexible diskette, 
and magnetic tape devices, this address must be on a word (even) 
boundary. For all other devices, the buffer can begin on an odd 
address. (See the section "XRB (Transfer Request Block)" in 
Chapter 2 for more information.) 
XRB+XRCI Channel number times two; defines the channel on which the 
data is to be written, as previously defined in an open (OPNFQ, 
CREFQ, CRTFQ, CRBFQ functions of CALFIP). 
XRB+XRBLKM For disk files, this byte contains the MSB of the starting block 
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number where the write is to begin. This byte is combined with 
the word at XRB+XRBLK to form a 24-bit field. 


XRB+XRBLK 


XRB+XRMOD 


Starting block number where the write is to begin. Performs 

the same action as the BLOCK option for disk or the RECORD 
option for flexible diskette and non-file-structured DECtape (see 
the RSTS/E Programming Manual). This parameter is ignored if 
the device is not a random-access device. If the device is random- 
access, and this field is nonzero, it is interpreted as the block 
number where the write is to start (1 to n, where n is the length 
of the file in 512-byte blocks). If zero, the next sequential block is 
written. For disk devices opened as non-file-structured in cluster 
mode, this value is the starting device cluster number where the 
write is to begin. 


Output operation modifier; significant only for line printer, termi- 
nal, and DMC/DMR devices. (The monitor informs you with the 
FLGMOD bit of the flag word whether or not the device accepts 
modifiers.) Except for modifier 20000, which is useful to MACRO 
programmers only, this parameter performs the same action as 
the BASIC-PLUS RECORD modifier for these devices (see the 
RSTS/E Programming Manual). 


Modifier 20000 provides a no stall option for line printer or 
terminal output. This modifier causes the monitor to return 
control to your program if an output stall is to occur on the device. 
You can determine the number of bytes still to be written by 
checking the contents of XRB+XRBC. 


Use this modifier for programs that must perform several different 
functions with optimal performance, such as a line printer spooler 
that performs message send/receive and prints files at the same 
time. When an output stall does occur, the program can perform 
other processing before trying to write the remaining bytes to the 
line printer or terminal. You may also find this modifier useful in 
multiterminal service applications. 


When you use the No Stall option on a line printer, you can 
perform a special test to see whether the line printer is busy 
without causing your program to stall. To perform the test, write 
a null character and set modifier bits 2 and 13. When both bits 
are set, the system returns control to your program instead of 
stalling it. The value at XRB+XRBC tells you the status of the 
line printer: 


XRB+XRBC = 0 The line printer buffers are empty; that 
is, there are no characters still to print. 
XRB+XRBC <> 0 The line printer buffers still contain one 


or more characters to print. Repeat the 
test until the system returns zero at 


XRB+XRBC. 


For more information on modifier bit 2 for line printers, see 
Appendix B and the RSTS/E Programming Manual. The 
RSTS/E Programming Manual also contains more information on 
special programming techniques for line printers. 
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Data Returned 


Mne— Octal 


monic Offset 


XRB 
Octal Mne-— 
Offset monic 


, . 
. 
XRBLKM 7 MSB of block number 6 
11 block number where write began 10 XRBLK 
XRB+XRBC The number of bytes not written in this .WRITE operation. Except 
for terminals and line printers, this value should be ignored. 
XRB+XRBLKM For disk files, the most significant bits of the block number of the 
block just written. (Combined with XRB+XRBLEK to form a 24-bit 
field.) | | | 
XRB+XRBLK For random-access devices, this word contains the block number of 
the block just written. Block numbers range from 1 to n, where n 
is the length of the file, in 512-byte blocks. They define the order 
in which the file is written. For disk devices opened as non-file- 
structured in cluster mode, this is the device cluster number of 
the cluster just written. 
Errors 
BADCNT The first three words of the XRB that describe the output buffer are illegal 
(an illegal byte count). 
BSERR The specified channel number is illegal; that is, it is not in the range 0 - 36 
(since channel is specified as channel * 2), or it is an odd number. 
EOF A write was attempted to a block beyond the end of the disk when the disk 
was opened non-file structured. 
NOTOPN No device is currently open on the specified channel. 
PRVIOL One of the following occurred: 


The file or device currently open on the specified channel is read-only. 
The open for this file or device did not specify write access. A write was 
requested that would extend a UFD or a contiguous file. 

A write was attempted that would extend a file in special update mode 
and block 0 was not locked. 


A write was attempted that would extend an executable file, increasing 
its size to more than 65,535 blocks. 


All other errors are device-dependent. Common errors are: 


DATERR 


HNGDEV 
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Some data error occurred. This error is issued when a parity error occurs, 
and so forth. 


Some hard device I/O error occurred. For example, the specified device is 
off-line, is physically write-locked, and so forth. 


NOROOM No more room is available on the device. For example, the end-of-tape 


marker has been encountered, no more available disk space, and so forth. 


Example 


The following code writes the contents of a buffer to the file open on channel 5: 


MOV #1024.,XRB+XRLEN ;SET BUFFER LENGTH 
MOV #1024.,XRB+XRBC ,;SET BYTES TO WRITE 
MOV #BUFFER, XRB+XRLOC ; SET BUFFER ADDRESS 
MOVB #5*2,XRB+XRCI ;SET CHANNEL = 5 
-WRITE 
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Part lil 
RSX and RT11 Emulator Directives 


Chapter 4 


RSX Run-Time system Environment 


Chapter 1 describes the RSX run-time system as emulating the RSX operating 
system environment on RSTS/E. This is only partially true; the RSX emulator 
does not provide a real-time, multiprocessing environment to users of a RSTS/E 
time-sharing system. However, the RSX emulator does process directives that 
are identical in form, and similar in objective, to a subset of the RSX-11M-PLUS 
monitor directives that the RSX-11M/M-PLUS Executive Reference Manual 
describes. 


If you use the RSX directives Chapter 5 describes, you must assemble your 
program with the MAC assembler and link the modules with the Task Builder 
(TKB). The program can then be run as a user job image under the control of the 
RSX emulator (which is part of the RSTS/E monitor). 


4.1 Advantage: Transportable Code 


The RSX emulator directives are useful if you are coding a program to be run 
under both the RSX-11M-PLUS and RSTS/E operating systems. However, 
RSTS/E does not emulate all RSX-11M-PLUS executive directives, and the 
meanings of those that are emulated are fitted to the RSTS/E environment. 


To design a program to be run under both operating systems, you need to know 
how the directives work under RSX-11M-PLUS and under RSTS/E. This manual 
describes what the directives do under RSTS/E. Some comparison is made here 
to RSX-11M-PLUS, but you must refer to the RSX-11M/M-PLUS Executive 
Reference Manual for a complete description of how these directives work in the 
RSX-11M-PLUS environment. 


Another benefit of using compatible directives is that you can execute such 
programs directly on VAX/VMS under the VAX-11 RSX Application Migration 
Executive (AME), which is similar in function to the RSX emulator. AME 
emulates most RSX-11M-PLUS executive directives. 


4.2 General Services 


Besides transportable code, the RSX emulator directives also provide: 


e Non-file-structured I/O—The RSX emulator directives handle only non-file- 
structured I/O (for example, terminal I/O). For this type of I/O, using the 
directives takes less memory than using RMS. See the RSTS/E RMS-11 
MACRO Programmer’s Guide for a description of the record management 
service capabilities for MACRO programmers. RMS routines are available to 
MACRO programmers through resident libraries or through linking to make 
them part of the user job image. In either case, the RMS routines take space 
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in the job area. The RSX emulator directives that do I/O take no extra space, 
since the code to handle the processing is in the monitor. 


e Trap handling—The RSX emulator includes processing to handle synchronous 
and asynchronous exceptions. Mainly, the emulator aborts the program when 
such exceptions occur and prints an error message at the job’s terminal. For 
some directives, you can request that this processing be bypassed and handle 
such exceptions in your program. For example, you can specify an address to 
pass control to when a Floating-Point Processor (FPP) exception occurs. 


4.3 RSX Directive Emulation Within RSTS/E Monitor 


RSX emulation is a standard feature of the RSTS/E monitor. This allows task 
images to execute without a run-time system, because the monitor handles the 
RSX emulation directly. As a result, task images may expand to be as large as 
64K-32 words; furthermore, a resident library (for example, RMS) may use the 
address space which would otherwise be taken by the run-time system. 


Since RSTS/E jobs are never without a run-time system, the monitor associates 
the job with a zero-length, run-time system called "...RSX" for the duration of 
the task’s execution. When the task ends, the job exits to its default keyboard 
monitor. 


4.4 System Macro Library 


The RSX emulator directives that you code into your program are macro; they 
must be expanded into executable code at assembly time. The system macro 
library (LB:RSXMAC.SML) contains the macro expansions for the RSX emulator 
directives. This library file can be named in the input-file list when the assembly 
is done. For example: 


MAC OBJ, OBJ=SRC1, SRC2,LB:RSXMAC.SML/ML 


However, the MAC assembler searches the library automatically to resolve 
undefined symbols, so this is not really necessary. 


In your code, though, you must use the MACRO-11 .MCALL directive to define 
the directives you use as external macros needed to assemble the source program. 
The .MCALL directive must appear before you call the first such directive. For 
example: 


~-MCALL ALUNS, QIOS 


ALUNS 2,TT,5 


Alternatively, you can use the .ENABL MCL assembler directive to enable 
automatic macro library search. See the PDP-11 MACRO-11 Language Reference 
Manual for details. 
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4.5 Directive Processing 


At assembly time, MAC expands the RSX directives to code. This creates a 
Directive Parameter Block (DPB) that defines the action to be taken and the 
parameters to be used. 


Figure 4—1 shows the general form of a DPB. 


Figure 4-1: General Form of the Directive Parameter Block 


DPB length (in words) | Directive ID Code (DIC 


(Parameters) 


The Directive Identification Code (DIC) in the low byte of the first word of 
the DPB defines the particular function to be performed. The RSX emulator 
examines the DIC to determine what it is supposed to do. The high byte of the 
first word of the DPB gives the length of the DPB in words (including the DIC 
and length byte). The remaining words contain parameters; usually these are 
values specified by the user in the directive call, expanded through MACRO-11 
data definition macros such as .BBYTE, .WORD, .RAD50, and so forth. 


The directive expansions also include executable code to tell the emulator where 
the DPB is, an EMT 377 instruction to pass control to the emulator and, op- 
tionally, transfer control to an error processing routine specified by the user. 


At execution time, RSTS/E pushes either the DPB address or the DPB itself on 
the stack. The choice depends on the form of the directive. The EMT 377 in- 
struction passes control to the RSTS/E monitor. The monitor recognizes the EMT 
377 and passes control to the RSX emulation in the monitor. The RSX emulator 
examines the DPB and processes the directive. It then pops the DPB address 

or the entire DPB off the stack and either returns control to the program that 
executed the directive or, if the directive was an exit of some kind, to whatever 
location is appropriate to the exit. 


When control returns in line, the carry condition code in the program status 
word (PSW) indicates that the directive executed successfully (carry code = 0) 

or failed (carry code = 1). The Directive Status Word gives more information 

on the success or failure of the directive. You can refer to the Directive Status 
Word in your program with the mnemonic $DSW; TKB defines this variable and 
resolves its location automatically at link time. Other mnemonics are similarly 
related to the possible values of $DSW, so the MACRO programmer can test for 
error conditions using symbols such as IS.SUC for successful completion. See 
"DSW Return Codes" in Chapter 5 for a listing of the symbols appropriate to each 
directive. 
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4.6 Directive Forms ($, $C, $S) and Their Expansions 


The library file RSXMAC.SML contains three different expansions for each of 
the RSX-11M directives (see Chapter 5). The form of the directive name you use 
determines which expansion to be inserted in your code. Directive names consist 
of one to four letters, followed by a dollar sign ($) and, optionally, a C or an S. 


Table 4-1 shows an example of the three forms for the ALUN$ directive (Assign 


Logical Unit). 


Table 4-1: Example of RSX Directive Forms 
Form Your Code Expansion Description 
$ A: ALUN$5,TTO A: BYTE 7,4 Create DPB in data section of 
’ -WORD 5 program (at assembly time) 
ASCII /TT/ 
.WORD 0 
: Push DPB address 
DIR$ #A,ERR MOV #A,-(SP) Call RSX emulator 
: | EMT 377 Branch if no error 
BCC .+6 Go to ERR on error 
JSR PC,ERR 
DIR$ #A,ERR (same as above) 
(same as above) 
$C ALUN$C 5,TT,0,PSEC1,ERR .PSECT $DPB$$ Create DPB at assembly time 
$$$=, and automatically put in sepa- 
BYTE 7,4 rate PSECT called $DPB$$ 
-WORD 5 
ASCII /TT/ 
.WORD 0 
.PSECT PSEC1 Reenter PSECT 
MOV #$$$,-(SP) Push DPB address 
EMT 377 Call RSX emulator 
BCC .+6 Branch if no error 
JSR PC,ERR Go to ERR on error 
$S ALUNS$S #5,#"TT,#0,ERR MOV #0,-(SP) Create DPB at execution time 
: MOV #'TT,-(SP) and push entire DPB on stack 
MOV #5,-(SP) 
MOV (PC)+,-(SP) 
BYTE 7,4 Call RSX emulator 
EMT 377 Branch if no error 
BCC .+6 Go to ERR on error 
JSR PC,ERR 
4.6.1. $ Form (and DIR$ Directive) 


As Table 4—1 shows, the $ form of an RSX emulator directive generates a DPB 
inline. The DIR$ directive expands to code that pushes the address of the DPB 
on the stack and passes control to the RSX emulator. Use the $ form/DIR$ 
combination when you want to repeatedly execute the same directive. After one 
directive defines a DPB, as many other DIR$ directives as need it, can use it. 
This technique saves memory. Also, you can modify the individual parameters in 
the DPB when you use the same directive many times with varying parameters. 
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$ Form 


The $ form of an RSX emulator directive expands to code that defines the DPB. 
The expansions consist of MACRO-11 data storage directives (for example, .BYTE, 
.WORD, .RAD50); they are not executable. Therefore, use the $ form of an RSX 
emulator directive only in a data section of your program. 


Finally, use parameters that fit the MACRO-11 data storage directive in which 
they will appear in the expanded code. For example, the ALUN$ directive 
expands to the four instructions that follow: 


ALUNS 5,TT,0 
Expansion: 


.BYTE 7,4 
.WORD 5 
.ASCII /TT/ 
.WORD 0 


Although the example uses the two-character second parameter (TT) in a 
MACRO-11 .ASCII directive, you do not need to specify the enclosing slashes; 
the expansion does that for you. 


Note that the first word of the expansion (the first word of the DPB) consists of 
two bytes. The 7 in the low byte is the DIC byte for the ALUN$ directive. The 4 
in the high byte indicates that the DPB is 4 words long. 


DIR$ Directive 
The general form of the DIR$ directive is: 
new DIR$ [adr] [,err] 


where: 


adr is the address of the first word of the DPB. As shown in the following expansion, 
this address must be a valid source address for a MOV instruction. (The adr 
parameter can be omitted. In this case, the entire DPB must be on the stack when 
the DIR$ is executed.) 


err is an optional error address. Control passes to this address if the directive does not 
execute successfully. If this parameter is omitted, control returns in line with the 
C-bit set in the program status word (PSW), 


For example, the DIR$ directive expands to the four instructions that follow: 


DIRS #DPB, ERROR 


Expansion: 

MOV —s«#DPB, - (SP) 
EMT 377 

BCC +6 

JSR PC, ERROR 


RSTS/E pushes the address of the DPB on the stack, and the EMT transfers 
control to the RSX emulator. The emulator processes the directive according to 
the parameters specified in the DPB, pops the DPB address off the stack, and (for 
ALUNS$) returns control in line. The BCC instruction branches around the JSR to 
ERROR if the C-bit is not set (no error occurred). 
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Other Features of $ Form/DIR$ Combination 


The $ form of the RSX emulator directives generates local offsets that you can 
use to refer to parameters in the DPB. 


NOTE 


The expansions use the MACRO-11 .NLIST directive so the code that 
generates these offsets (which is not of interest to your program) does 
not show up in your assembly listings. 


For example, in the ALUN$ directive, you specify a logical unit number, physical 
device name, and device unit number: 


LN5DEF: ALUNS 5,TT,O 


When this directive is expanded, it includes code that allows you to refer to the 
parameters as: 


LN5DEF+A.LULU Logical unit number 
LN5DEF+A. LUNA Device name 
LN5DEF+A.LUNU Unit number 


Chapter 5 lists these offset names under "Local Symbol Definitions" for each 
directive. The number of bytes defined for each offset is given in parentheses 
following a description of the area referenced by the offset. For example: 


A.LUNU — Logical unit number (2) 


(You can also use offset names with the $C form of directives. However, you 
cannot use offset names with the $S form because $S generates values that are 
pushed on the stack.) 


The $ form expansions are also designed so you can use them to simply set up the 
offset symbols to reference a DPB in another module. If you define the symbol 
$$$GLB in your program (for example, $$$GLB = 0 will do), the $ form of any 
directive generates the symbolic offsets as global symbols and does not generate 
the DPB itself. For example, suppose another module has the following code: 


MYMY:: ALUNS 5,TT,0 


In the current module, define MYMY as a global symbol, define $$$GLB, specify 
an ALUN$, and you will be able to reference MYMY+A.LULU, and so forth. 


4.6.2 $C Form 


If you know the DPB parameters at assembly time and need to issue a directive 
only once, the $C form saves you the trouble of coding two directives: the $ form 
and DIR$. The $C form also saves execution time over the $S form, which uses 
MOV instructions to place the entire DPB on the stack and may save space as 
well. 


The $C form of the directives expands to code that: 
¢ Defines the DPB in a separate PSECT (called $DPB$$). 


e Returns to a user-specified PSECT. If no PSECT name is given, returns to the 
blank (unnamed) PSECT. 
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e Pushes the DPB address on the stack. 
° Passes control to the RSX emulator. 


e On return, passes control to a user-specified error routine if the directive did 
not execute successfully. If you did not specify an error routine, no such code 
is generated. | 


The directive descriptions in Chapter 5 show the form and expansion for the 
¢$ form. To use the $C form, you must add the C to the directive name and, 
optionally, add a PSECT name and error address to the parameter list. For 
example, the ALUN$C directive expands to the 11 instructions that follow: 


ALUNSC 5,TT,O,PART1,ERROR 


Expansion: — 

.PSECT SDPBS$ 
$$$= 

. BYTE 7,4 

. WORD 5 

.ASCII /TT/ 

. WORD 0 

.PSECT PART1 
MOV #$593,- (SP) 
EMT 377 

BCC +6 

JSR PC, ERROR 


MAC places the DPB in a separate PSECT called $DPB$$. The $$$ symbol 
equates to the address of the DPB, which MAC uses in the MOV instruction that 
pushes the DPB address on the stack before control passes to the emulator by the 
EMT instruction. The last two instructions set up the test for error and transfer 
control to the specified error routine. If you do not specify an error address in the 
call, MAC does not generate those instructions. 


Other Features of $C Form 


The offset mnemonics that MAC generates for the $ form are also generated for 
the $C form. Thus, you can save space by using the $$$ address to form the base 
address for the offsets. The $$$GLB feature for the $ form also works for the $C 
form of the directives. 


4.6.3 $S Form 


The $S form is useful if your code is reentrant and the DPB parameters vary. 
RSTS/E generates the DPB when it executes the directive at run time. 


The $8 form of the directives expands to code that: 
e Generates the DPB at execution time and pushes it on the stack. 


-¢@ ‘Transfers control to the RSX emulator. The RSX emulator checks the low 
byte of the first word on the stack to determine if it is a DPB address (even 
low byte) or a DIC (odd low byte). If the low byte is odd, then the emulator 
knows that the rest of the DPB is on the stack. 


e On return, passes control to a user-specified error routine if the directive 
did not execute successfully. If no error routine is specified, no such code is 
generated. 
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To use the $S form of the directives, add S to the directive names shown in 
Chapter 5. You can also specify an error address as the last parameter in the 
line. For example, the ALUN$S directive expands to the eight instructions that 
follow: 


ALUNSS  #5,DEV,UN,ERR 


Expansion: 

MOV UN, - (SP) 
MOV DEV, - (SP) 
MOV #5,-(SP) 
MOV (PC) +,-(SP) 
. BYTE 7,4 

EMT 377 

BCC +.6 

JSR PC, ERR 


RSTS/E generates the DPB at run time and pushes it on the stack. Control 
passes to the RSX emulator, and if control returns with an error (the C-bit is set 
on return), control transfers to the error routine. If you do not specify an error 
address in the call, MAC does not generate the last two instructions. 


4.7 Using Resident Library Access Directives from FORTRAN 


When programming resident library access in FORTRAN, you must create an 
eight-word, single-precision integer array as the RDB to be supplied from the 
following routines: 


e CALL ATRG (Attach Region directive) 

e CALL CRRG (Create Region directive) 

e CALL DTRG (Detach Region directive) — 

See the PDP-11 FORTRAN IV Language Reference Manual or the PDP-11 
FORTRAN Lanugage Reference Manual for information on the creation of arrays. 


An RDB array has the following format: 


Word Contents 

irdb(1) Region ID 

irdb(2) Size of the region in 32-word blocks 

irdb(3) Region name—two words in RAD50 format 

irdb(4) 

irdb(5) Name of the partition that contains the region— two words in RAD50 
irdb(6) format 

irdb(7) Region status word. See the paragraph following this table. 

irdb(8) Region protection code. 


You can modify the region status word irdb(7) by setting or clearing the 
appropriate bits, listed with each directive. 


Note that Hollerith text strings can be converted to RAD5O values by calls to the 
FORTRAN library routine IRAD50. 
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4.8 First 512. Bytes of Low Segment for RSX 


As Chapter 2 notes, the first 512. bytes of virtual address space have special 
meaning to the monitor. TKB, which links programs assembled or compiled 
under the RSX run-time system and its derivatives, generates a header for 
your executable program. When the RSX emulator loads your program, it uses 
information from this header to load certain values into the low 512. bytes of 
your program. 


Table 4—2 shows the allocation of the first 512. bytes of the low segment for 
RSX-type programs. Note that all locations are subject to change except for 
$DSW, KEY, FIRQB, XRB, and CORCMN. 


Table 4-2: First 512. Bytes of Low Segment for RSX 


Offset 


0 
2 


112 


200 


Mnemonic 


R.TSKN 


R.PRTN 


R.CDSZ 
R.ODTV 
R.ODTL 
R.SSTV 
R.SSTL 
R.FAST 
R.CAST 
R.TSKE 
R.PARM 
R.CCLF 
R.LDSZ 
R.TKSZ 
R.LUN 
R.MONI 
R.MON2 
$DSW 
.ESRPT 
$0TSV 
N.OVPT 
$VEXT 
CONTXT 


FPPTXT 


R.LUNS 


Description 


Task name in RAD50 
Partition Name in RAD50 


Task Size (without extension, 32-word blocks) 
ODT SST Vector Address 

ODT SST Vector Length (low byte only) 

Task SST Vector Address 

Task SST Vector Length (low byte only) 

FFP AST Service Address 

CTRL/C AST Service Address 

Task Flags 

Run Parameter on Entry (from FIRQB+FQNENT) 
CCL Entry Flags, Run Size/Extension (XRB+0) 
Load Size of Task in 32-word blocks 

Current Size of Task in 32-word blocks 
Number of LUNs 

Monitor RSX Emulation Reserved Word 1 
Monitor RSX Emulation Reserved Word 2 
Directive Status Word 

FCS Impure Area Pointer 

OTS Impure Area Pointer 

Auto-Load Impure Area Pointer 

Extended Impure Area Pointer 

(Reserved for Monitor Context Use) 


(Reserved for Monitor FPP Context Use) 
LUN Table 


(continued on next page) 
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Table 4-2 (Cont.): 


Offset 


400 
402 


442 
460 


660 
662 


722 
134 
736 


740 


1000 
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Mnemonic 


CORCMN 


PDMSP 
PMDXRB 


USRPPN 
USRPRT 
USRLOG 


NSTORG 


First 512. Bytes of Low Segment for RSX 


Description 
or 

FIRQB 

XRB 

Core common area 


SP saved here on a PM dump 


XRB saved here on a PM dump 
FIRQB also saved on PM dump starting at PMDXRB 


SP stack space for RSX Emulator 
User’s assignable project, programmer number 
User’s assignable protection code 


User’s logical device table 


Stack guard word (must = 0) 


Chapter 5 


RSX Emulator Directives 


The RSX emulator directives: 

e Perform non-file-structured I/O 

e Let you specify your own exception-handler routines 
¢ Control execution of the program 

e Return system information to the job 


e¢ Provide access to resident libraries 


Table 5-1 lists these directives by function. The remaining sections of this 
chapter present the directives in alphabetical order. 


Table 5-1: Summary of the RSX Directives 


Name | Description 
Non-File-Structured I/O 

ALUN$ Assigns a logical unit number to a device and unit. The logical unit 
number then serves to define the device in I/O requests. 

GLUN$ Returns information about a logical unit. 

GMCR$ Returns the command line typed by the user to invoke the program 
currently running, if it was invoked by a RSTS/E CCL command. 

— QIO$ Open, read from, write to, and close logical units. I/O in RSX-emulation 
QIOW$ mode is synchronous. That is, it is not asynchronous as in some systems, 


such as RSX-11M where a user program can request I/O, do other process- 
ing, and get an interrupt when the I/O is complete. Thus, under the RSX 
emulator, QIO$ (queue input/output) and QLOW$ (queue input/output and 
wait) do the same thing. Control returns to the calling program when the 
YO is done. 


WSIG$ Provides compatibility with RSX-11M, where some recoverable error 
conditions require waiting for some significant event to occur before 
retrying the operation that caused the error. In RSTS/E, such events are 
transparent to the user program. WSIG$ simply causes the program to 
sleep for one second. 


WTSE$ Provides compatibility with RSX-11M, where RSX uses QIO$ and WTSE$ 
together to cause the program to wait until I/O is completed. Since I/O in 
- RSX-emulation mode is synchronous, the WI'SE$ is implemented here as 

a NOP instruction. 


(continued on next page) 
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Table 5-1 (Cont.): Summary of the RSX Directives 


Name 


ASTX$ 


SCCA$ 
SFPA$ 


SSTX$ 


SVDB$ 


SVTK$ 


ABRT$ 


EXIT$ 
EXST$ 


EXTK$ 


EXTM$ 


SPND$ 


5—2 RSX Emulator Directives 


Description 
Exception Handling 


Exits from an FPP exception-handling routine, restoring the DSW, PC, and 
PSW to the values they had before the exception occurred. 


Defines an address to which control passes when a user at the job’s 
terminal types a CTRL/C combination. The SCCA$ directive is unique to 
RSTS/E; it does not exist in the RSX-11M operating system. 


Specifies an address to which control is to pass when an FPP exception 
occurs. (The FPP is available on all PDP-11 processors that can run 
RSTS/E, except the PDP-11/35 and 40.) 


Terminates routines that handle synchronous system traps with SVDB$ or 
SVTK$. Required if the program uses supervisor mode libraries. Returns 
control to where the program left of at the time of the trap. The SSTX$ 
directive is unique to RSTS/E; it does not exist in the RSX-11M operating 
system. 


Specifies a table of synchronous exception addresses that are to override 
any specified with an SVTK$ directive. This is a useful capability for 

a debugging routine, to divert breakpoint traps, for example, to the 
debugging routine regardless of any SVTK$ directive in other modules of 
the job. 


Specifies a table of addresses to which control is to pass when synchronous 
exceptions occur. The job can handle eight possible exceptions including 
PDP-11/35 and 40 FIS errors, TRAP instructions, BPT instructions, IOT 
instructions, and T-bit traps. 


Program Execution Control 


Sets the job’s exit status to "Severe Error” and returns control to the job’s 
keyboard monitor. 


Returns control to the job’s keyboard monitor (a normal exit). 


Sets the job’s exit status to the specified value and returns control to the 
job’s keyboard monitor. 


Increases or decreases the amount of memory allocated for execution of the 
user job image. 


Increases or decreases the amount of memory allocated for execution of the 
user job image and allows manipulation of the D-Space APRs according to 
a mask. 


Suspends execution of the program until the user types a delimiter on the 


keyboard (KB:). 


(continued on next page) 
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Name 


FEADF$ 
FEAT$ 
GPRT$ 


GTIM$ 
GTSK$ 


TFEA$ 


Description 
System Access Information 


Defines system feature labels. 
Tests for specified system features. 


Returns partition parameters, which contain general information about 
the job area and user job image area. 


Returns the current day and time. 


Returns task parameters: run priority, PPN, number of logical units 
assigned, address of SST vector table (set up the SVITK$ or SVDB$), and 


the system in which the job is running. 


Tests for specified task features. 


Resident Libraries Access 


ATRG$ 


CRAW$ 


CRRG$ 
DTRG$ 
ELAW$ 


Fast-map 


MAP$ 


MSDS$ 


RDBBK$ 


RDBDF$ 
UMAP$ 


WDBBK$ 


WDBDF$ 


Attaches the job to a resident library, laying the groundwork for access to 
the library. If necessary, the resident library is loaded from disk. 


Creates a window of virtual addresses for reference to a library. 
Optionally, you can map the window to actual locations in a resident 
library. 

Creates a dynamic region and optionally attaches to it. 

Detaches the job from a resident library. 


Eliminates an address window; it releases the virtual addresses for other 
use, such as expanding the job image or creating another window. 


Relates a created address window to actual memory locations in an 
attached resident library. Fast-mapping is a simplified, high-speed alter- 
native to MAP$. 


Relates a created address window to actual memory locations in an 
attached resident library. The user program can then refer to locations in 
the library using the virtual addresses defined in the window. 


Specifies a 7-bit mask that determines which space each supervisor 


D-space APR will use. 
Defines the offsets shown for the RDB areas for the ATRG$ and DTRG$ 


directives and, in addition, generates code to allocate space for the RDB 
and fills it with values you specify in the call. 


Assigns literal values to the offsets and status bit mnemonics shown for 
the RDB areas for the ATRG$ and DTRG$ directives. 


Unmaps a window from a library; you can then map the window to 
another portion of the library or to a different library. 


Defines the offsets shown for the WDB areas for the CRAW$, ELAW$, 
MAP$, and UMAP$ directives and, in addition, generates code to allocate 
space for the WDB and fills it with values you specify in the call. 


Assigns literal values to the offsets and status bit mnemonics shown for 


the WDB areas for the CRAW$, ELAW$, MAP$, and UMAP$ directives. 
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5.1 ABRT$ — Abort 


5-4 ABRT$ 


The ABRT$ directive terminates execution of the calling program. Any open files 
or devices are reset (that is, closed without the usual clean-up operations). On 

a RSTS/E system, ABRT$ acts the same as the EXST$ directive with a severe 
error. 


Control passes to the job keyboard monitor at the keyboard monitor entry point 
P.NEW (see Chapter 2). The job keyboard monitor is the default keyboard 
monitor unless the job has issued the SET JOB/KEYBOARD_MONITOR 
command or executed the .RTS directive to establish a specific job keyboard 
monitor (see Chapter 3). 


Privileges Required 
None 


Macro Call 
ABRT$ name 


RSTS/E ignores the name parameter; the calling program can abort only itself. 


Macro Expansion 


ABRTS ALPHA 
» BYTE 834.3 ;DIC=83., DPB SIZE = 3 WORDS 
»RAD50 /ALPHA/ ; IGNORED IN RSTS/E 


Local Symbol Definitions 


A.BTTN name (4) 


DSW Return Codes 


IE.SDP DIC or DPB size is invalid. This does not occur unless your program changes 
the value of the first word of the DPB during execution. Control does not 
otherwise return inline for the ABRT$ directive. 


5.2 ALUN$ — Assign Logical Unit Number 


The ALUN$ directive assigns a logical unit number (LUN) to a physical device 
unit. You can then use the logical unit number in QIO$ or QIOW$ directives to 
do I/O (open, read, write, or close the associated device). 


You can specify the device name as any 2-character logical name. The RSX 
emulator checks the name specified in the call against the user logical names; if a 
match is found, the monitor assigns the logical unit number to the corresponding 
physical device. If the device name specified does not match any user logical 
device names, the monitor performs a similar search for a match with a system- 
wide logical device name. If there is no match, the emulator checks the monitor’s 
physical device table, and, if a match is found, assigns the logical unit number 
specified in the call to the actual physical device unit specified. Otherwise, the 
directive returns an error. 


Privileges Required 
If the device is restricted, DEVICE is required. 


Macro Call 

ALUNS$ lun,dev,unt 

where: 

lun is the logical unit number; 1-14. 

dev is the device name; two ASCII characters. 

unt is the device unit number. Minus one indicates no unit number, as opposed to 


a unit number of zero. The RSX emulator does not make a distinction between 
SY (meaning the public disk structure) and SYO (meaning the disk from which 
the system was booted). All uses of SY refer to the public structure. TI, TT, and 
KB all refer to the job’s terminal, whereas KBO and TTO both refer to the system 
console terminal. 


Macro Expansion 


ALUNS 5,TT,0 

. BYTE Ty ;ALUNS MACRO DIC=7, DPB SIZE=4 WORDS 
. WORD 5 ;LOGICAL UNIT NUMBER 5 

.ASCII /TT/ ;DEVICE NAME IS TT (TERMINAL) 

. WORD 0 ;DEVICE UNIT NUMBER=0 


Local Symbol Definitions 


A.LULU Logical unit number (2) 
A.LUNA Physical device name (2) 
A.LUNU Physical device unit number (2) 


DSW Return Codes 


[IS.SUC Successful completion. 
IE.IDU Invalid device and/or unit. 


TE.ILU Invalid logical unit number. 
TE.SDP DIC or DPB size is invalid. 
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5.3 ASTX$ — Asynchronous Exception Exit 


5-6 ASTX$ 


In the RSTS/E environment, you can use the ASTX$ directive to terminate a 
routine that handles an asynchronous FPP exception, only if the program has 
indicated its intention to handle such traps with an SFPA$ directive. No other 
condition in RSTS/E causes an asynchronous exception from which an ASTX$ exit 
is useful. The Ctrl/C exception should use the SSTX$ macro to exit properly (see 
SCCA$S). 


When you execute an ASTX$, the stack must be in the state: 


(DSW) at the time exception occurred 

(PC) at the time exception occurred 

(PS) at the time exception occurred 

word to which SP pointed before the exception 


Your routine must pop the Floating-Point Exception Code (FEC) and Floating- 
Point Address (FEA) pushed on the stack when the exception occurred (see 
SFPA$). 


When the ASTX$ directive executes, the RSX emulator restores the DSW value 
to the DSW location and loads the PC and PS registers with their appropriate 
values. Thus, these values pop from the stack, and control returns to the user 
program at the point where it left off when the exception occurred. 


You can change the contents of the PC address in the stack before you execute 
ASTX$ so RSTS/E passes control to some point other than where it left off. Use 
caution because it is hard to debug errors in an asynchronous exception routine. 


Privileges Required 
None 


Macro Call 
ASTX$ [err] 
where: 


err is the error routine address 


Macro Expansion 


ASTXSS ERR 

MOV (2C):+,.— (SF) 7;PUSH DPB ONTO THE STACK 

- BYTE lO wp oe ?;DIC = 115., DPB SIZE = 1 WORD 

EMT odd ; TRAP TO RSX EMULATOR 

JSR PC, ERR ;JUMP TO ERR IF DIRECTIVE UNSUCCESSFUL 


NOTE 


Digital recommends the $S form for this directive for two reasons: 
first, only a one-word DPB is generated; second, no BCC instruction is 
generated for the $S form (or the $C form). Thus, the $S form takes 
less space than the $form/DIR$ combination. In addition, since the 
one-word DPB requires only one MOV instruction, the $S form takes 
less space and no more execution time than the $C form. 


Local Symbol Definitions 


None 


DSW Return Codes 


TE.SDP DIC or DPB size invalid. This occurs only if your program changes the first 
word of the DPB at execution time. 
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5.4 ATRG$ — Attach Resident Library 


The ATRG$ directive attaches the job to a resident library. The type of access 
(read-only or read/write) is specified in the call. If the calling job can access the 
library in that fashion, the monitor sets up its own internal tables that lay the 
groundwork for the job to map windows to the library. Note, however, that the 
resident library does not take up space in the job area (virtual memory) with an 
attach. Virtual memory is assigned when a window is created (CRAW$). 


NOTE 


The job’s ability to access the resident library depends upon the 
protection assigned by the system manager when the resident library 
was installed. The default protection grants read access to all users 
and denies write access to all users. 


If the attach is successful, a resident library ID is returned to the job. Other 
directives use this ID to detach the job from the library (DTRG$) or to map and 
unmap windows to and from the library (MAP$ and UMAP$). Once the monitor 
attaches the job to a library, you can use the ATRG$ directive to determine the 
library ID. 


You can attach an unlimited number of resident libraries to a job at any given 
time, provided the system has enough resources to keep track of the list of 
attached libraries. 


Privileges Required 


None 


Macro Call 
ATRG$ adr 
where: 


adr specifies the address of an 8-word area defining the library to be attached and 
the type of access desired. The ATRG$ directive returns information to this area. 
Two supplementary directives are available to define (RDBDF$) or define and 
fill (RDBBK$) such an 8-word area, called the resident library definition block 
(RDB). 


Macro Expansion 


ATRGS RDBLK 
~- BYTE ST ape ;DIC = 57., DPB SIZE = 2 WORDS 
» WORD RDBLK ; ADDRESS OF RDB 
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Data Passed in RDB 


Mne— Octal 
monic Offset 


adr+R.GNAM 


adr+R.GSTS 


adr+R.GSTS 


LITIIITIII IITA TT 
PTAA IATA TAP TAT 


ee 


Octal Mne-— 
Offset monic 


resident library name 4 R.GNAM 


(2 words in RADS50 format) 


14 R.GSTS 


is the name of the resident library to which the job is to be attached, 
as two words of RAD50 data. (The system manager makes resident 
libraries known to the RSTS/E monitor with the INSTALL/LIBRARY 
command (see the RSTS/E System Manager’s Guide). With this com- 
mand, the system manager defines a file (filename.LIB) as a resident 
library. The monitor regards "filename" as the resident library's name.) 


is the low-order two bits in this word which defines the desired access 
to the library. 


RDBBK$, 
RDBDF$ 


are the status bits that are currently defined as follows: 
Bit Definition 


Read access desired on attach. 

Write access desired on attach. 

Delete access desired on attach. 

Attach to region (forced if unnamed region). 


Do not mark created region for deletion on last detach. 


ID OF WD KH © 


Delete region when all users detach (forced if unnamed 
region). 


14 At least one window was unmapped on a detach. 


15 Region was successfully created. 


Once RSTS/E attaches a job to a resident library, the access cannot be 
changed without detaching (DTRG$) and reattaching. Also, an ATRG$ 
with the same resident library name specified at adr+R.GNAM returns 
the assigned resident library ID. 
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Data Returned to RDB 


Mne— 
monic 


adr+R. 


adr+R. 


Local 


Octal Octal Mne- 
Offset Offset monic 
1 resident library ID 0 R.GID 
3 size of library, in 32—word pigeks 2 R.GSIZ 
5 TTT TTL TTT 4 
7 TTT 6 
11 AE TET LAA Cb id 10 
13 | (TTT TTT TATA 12 
15 TTT TTA 14 
16 
GID is an identifier which must be used in subsequent calls to identify a 
resident library, rather than the resident library name. Thus, you use 
this identifier to detach (DTRG$) and to map and unmap windows 
(MAP$ and UMAP$) to the library. 
GSIZ is the size of the resident library, in 32-word blocks. 
Symbol Definition 


A.TRBA Resident library definition block address (2) 


DSW Return Codes 


IS.SUC Successful completion. 


TE.UPN 


IE.PRI 


IE.PNS 


are currently available. 


Attaching a job to a resident library requires a small buffer; no small buffers 


The attach did not succeed because the caller’s privileges do not allow the 
access requested. This could happen either because the access code specified 
is not compatible with the possible access defined when the library was 
installed by the system manager or because the protection code associated 
with the resident library file excludes the access requested by the user. 


The resident library name specified is not known to the monitor. The system 


manager must install a resident library before the system can use it. 


5.5 CRAWS$ — Create Address Window 


You can use the CRAW$ directive either to create a window (a range of virtual 
addresses) or to create a window and map it to a range of actual addresses in an 
attached resident library. You define the range of addresses by naming a base 
APR, which defines the starting virtual address for the window, and by specifying 
the size of the window in 32-word blocks. Thus a window always begins on a 4K- 
word boundary in virtual memory. It may take more than 4K words, depending 
on the size of the window. 


The difference between creating a window and creating and mapping a window 
is best illustrated by example. By using create without map, you can define 

one window, which can be mapped to a library or portion of a library and then 
remapped using MAP$ to another portion of the same library or another library, 
as many times as desired. For example, suppose your program takes up 24K 
words, and you want to access a 24K-word resident library of data values. You 
can use create without map to set up a 4K-word window in APR 6. You can then 
map the window to the first 4K words of the library, process the data, map to the 
next 4K words of the library, and so forth. 


If, on the other hand, you had a 4K-word program and still wanted to access a 
24K-word library, you could use CRAW$ to create a 24K-word window and map it 
to the entire library in APRs 1-6. 


A job can create a maximum of 22 windows. A window takes at least one APR, 
possibly more, depending on the size you specify for the window. Thus, the 
maximum of 22 assumes 22 4K windows in both user I-Space and D-Space APRs 
1 through 7 and eight 4K windows in supervisor I-Space APRs 0 through 7. You 
can never use user I or D APR 0 to create a window, since the user program takes 
at least this much space. As mentioned previously, a window cannot overlap 
the user job image; thus, the size of the user job image determines the lowest 
base APR that the job can use. If the program (user job image) is 4K words or 
less, you can use APRs 1 and up (to the limit imposed by the run-time system 
boundary) to create windows. If the user job image is between 4K words and 8K 
words, you can use APRs 2 and up to create windows, and so forth. 


If the virtual address range overlaps the user job image, the call fails with an 
error. If the address range overlaps any existing windows, the overlap condition 
is handled in a number of different ways, depending on the type of windows that 
overlap: 


e Ifthe job has nonseparate I&D Space or a Supervisor window is being 
created, the new window eliminates all existing windows that it overlaps. 


e Ifthe job has seperate I- and D-Spaces and the new window request has the 
same D-Space mapping bit value (WS.UDS) as any overlapping windows, 
the new window eliminates the old overlapping windows. For example, if a 
window exists in I-space (WS.UDS=0) and a new window request, also with 
WS.UDS=0, overlaps it, then the new window eliminates the existing window. 
The new window also eliminates the existing window if both windows have 
WS.UDS=1. 


e If the new window being created is D-Space only (WS.UDS=1) and it overlaps 
a window which is currently in both I- and D-Spaces (WS.UDS=0), the new 
window eliminates only the D-Space portion of the existing window, leaving 
it in I-Space only. The new window then resides in the D-Space concurrently 
with old window in I-Space. Note that the entire D-Space portion of the 
existing window is eliminated even if only a portion of it overlaps with the 
new window. 
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e Likewise, if an 1&D-Space window overlaps an existing D-Space-only 
window, only the I-Space of the new window gets created and the existing 
D-Space-only window remains. 


Use caution when creating concurrent windows (one in I-Space only and one 
in D-Space only). The default condition when creating I-Space windows is that 
the equivalent D-Space accompanies it. The library being mapped through this 
method must be writen as I-only code (such as RMS-11) if the D-Space is to be 
given to another window. If it is not I-only code, then you will get unpredicable 
results if its D-Space is given away. 


Privileges Required 


None 


Macro Call 
CRAW$ adr 
where: 


adr _ is the address of an 8-word area defining the window and the resident library 
to which the window is to be mapped, if mapping is requested. The CRAW$ 
directive also returns information to this area. Two supplementary directives are 
available to define (WDBDF$) or define and fill (WDBBK$) such an area, called 
the window definition block (WDB). 


Macro Expansion 


CRAWS WDB 
- BYTE Lege ;DIC = 117., DPB SIZE = 2 WORDS 
- WORD WDB ; ADDRESS OF WDB 


Data Passed in WDB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
s[reitiuriiinin | + 

5 size, in 32-word Bingke: of window 4 W.NSIZ 


adr+W.NAPR is the base APR of the window, 1-7 that implicitly defines the starting 
address of the window. This byte cannot be zero, nor can it name 
an APR already being used to map the user job image (see previous 
discussion). 


adr+W.NSIZ Is the desired size of the window, in 32-word blocks. For example, a 
value of 128 = 4K words. 
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adr+W.NRID is the identifier of the resident library to which the window is to be 
mapped. (This is the value returned at adr+R.GID in the RDB for an 
ATRG$ directive.) This word is ignored for calls requesting a create 
without mapping (bit 7 at adr+W.NSTS is zero). 


adr+W.NOFF is the offset, in 32-word blocks, from the start of the library where the 
mapping is to begin. This word is ignored if no mapping is requested 
(bit 7 at adr+W.NSTS is zero.) A value of zero for this word indicates 
the window is to be mapped beginning at the first byte of the library. 
A value of one indicates the window is to be mapped beginning at the 
33rd word of the library (starting address + 64), and so forth. 


adr+W.NLEN is the length, in 32-word blocks, of the area to be mapped (ignored if 
bit 7 at adr+W.NSTS is zero). This value cannot be greater than the 
length of the window specified at adr+W.NSIZ. In addition, this value, 
combined with the offset specified at adr+W.NOFYF, cannot indicate an 
address beyond the end of the library. A value of zero defaults to either 
the size of the window or the space remaining in the library, whichever 
is smaller. 


adr+W.NSTS is the access-flags word. Two bits of this word define whether the 
window is to be mapped and whether read-only access or read/write 
access to the window is desired. Two additional bits define whether the 
the window is to be mapped into supervisor I-Space or User D-Space. 
If neither WS.SIS nor WS.UDS are set, then the CRAW$ directive uses 
User I-Space. 


WDBDF$, 
WDBBK$ 
Mnemonic Bit Meaning 
WS.64B 8 an | The task’s permitted alignment bound- 
aries defined as 32 words. 
= 0 The task’s permitted alignment bound- 
aries defined as 256 words. 
WS.MAP 7 =. The window is to be mapped. 
=0 The window is not to be mapped. 
WS.SIS 5 = 1 CRAWS$ allocates this window in the 
supervisor I-Space. Any mapping 
occurs in the supervisor I-Space APRs 
only. 
= 0 This window is not a supervisor mode 
window. 
WS.UDS 4. =1 CRAW$ allocates this window in the 
User D-Space. Any mapping occurs in 
User D-Space APRs only. 
= 0 This window is not a data-only window. 
WS.WRT 1 | Read/write access is desired. 
= 0 Read-only access is desired. 


If neither bit 4 nor bit 5 is set, then user Instruction Space is used. There is a 
functional correspondence between bits 4 and 5 in the CRAW$ mode byte and the 
region options available in TKB. This correspondence is as follows: 


TKB Option CRAW$ Mode Bit Setting 
RESCOM & COMMON bit 4 set to 1 

RESSUP & SUPLIB bit 5 set to 1 

RESLIB & LIBR neither, bit 4 & 5 set to 0 
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If bit 4 = 1, the window is created in the D APR space only; no mapping in the 
I-Space is done. If another window is already created in both the I- and D-Space 
at this APR, the I-Space window remains as is, but the D-Space window moves 
to this request. If a CRAW$ is done with bit 4 set and a second CRAW$ is done 
to the same APR with neither bit 4 nor bit 5 set, the resulting mapping is such 
that the D-Space APR is given to the CRAW with bit 4 set and the I-Space APR 


is assigned to the region of the second CRAW$. 


It is illegal to CRAW$ a region with both bits 4 and 5 set. In RSTS/E, supervisor 
D-Space is always initially mapped the same as user D-Space. See the MSDS$ 


directive. 


Data Returned in WDB 


Mne-— Octal Octal Mne- 
monic Offset Offset monic 
3 starting virtual address of window 2 W.NBAS 
5 PALLAL ELIA ELLA ALLA 4 
7 PEAT ITAT TATA i 6 
13 length, in 32—word blocks, mapped 12 W.NLEN 
17 PTAA ATT AAT I AAT dd ad 16 
adr+W.NID is the window ID, a value from 1-7. You can use this ID in later MAP$ 
calls to map the newly created window. You must use the ID in any 
ELAWS$ calls to eliminate the window. 
adr+W.NBAS is the starting virtual address of the new window. 
adr+W.NLEN is the length, in 32-word blocks, actually mapped by the window. 
adr+W.NSTS is the status-flags word. 
WDBDF$, 
WDBBK$ 
Mnemonic Bit Meaning 
WS.CRW 1564 The window was created successfully 
= 0 The window was not created 
WS. ELW 13 =1 An existing window was eliminated be- 
cause it overlapped the newly created 
window 
= 0 No existing windows were eliminated by 
this create 
WS.UNM 14=1 An existing window was unmapped be- 
cause it overlapped the newly created 
mapping 
= 0 No existing windows were unmapped by 


Local Symbol Definitions 


C.RABA 
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this mapping 


Window definition block address (2) 


DSW Return Codes 


IS.SUC 
TE.ALG 


IE.NVR 


IE.PRI 


IE.WOV 
IE.UPN 


Successful completion. 


Hither the base APR and window length specified were invalid or the offset 
and mapping length values specified were invalid. For example, an offset 
indicating a starting address for the mapping that was beyond the end of the 
library returns this error. 


The library ID specified for mapping does not specify any library currently 
attached to the job. 


The create was unsuccessful because the requested access is not allowed. At 
this point, since the library has been attached successfully with some access 
defined, this error means that the access requested in the CRAW$ is not 
allowed by the access requested in the ATRG$. 


An attempt was made to create more than seven address windows. 


Creating a window requires a small buffer; a small buffer is not currently 
available. 
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5.6 CRRG$ — Create Dynamic Region 


The CRRG$ directive creates dynamic regions similar to those created by 
UU.RTS. This call operates in a slightly different manner than its counterpart. If 
an attempt is made to create a region that already exists, CRRG$ returns with 
bit 15 in R.GSTS clear. If attachment is specified and the region already exists, 
the new region is attached to the already existing region. 

Privileges Required 


INSTAL 
Macro Call 
CRRG$ adr 


where: 


adr is the address of an 8-word Region Descriptor Block (RDB). The CRRG$ directive 


also returns information to this area. 


Macro Expansion 


CRRGS RDBLK 
- BYTE Doe5-2 ;DIC = 55., DPB SIZE = 2 WORDS 
- WORD RDBLK ; ADDRESS OF RDB 


Data Passed in RDB 


Mne-— = Octal Octal Mne- 
monic Offset Offset monic 
1 PTAATALLA TAIT TAP TE 0 
3 size in 32—word blocks of region to create 2 R.GSIZ 
5 name of region, or 0 for unnamed 4 R.GNAM 
| (2 words) 
7 6 
11 VIATATATATATAT IAL TIA 10 
13 FATTATALELIAM TALI TA 12 
17 region protection in RSX format 16 R.GPRO 
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adr+R.GSTS are the status bits that are currently defined as follows: 
Bit Definition 
0 Read access desired on attach. 
1 Write access desired on attach. 
3 Delete access desired on attach. 
5 Attach to region (forced if unnamed region). 
6 Do not mark created region for deletion on last detach. 
7 Delete region when all users detach (forced if unnamed 
region). 
14 At least one window was mapped on a detach. 
15 Region was successfully created. 
adr+R.GPRO is the region protection code converted from RSX format to RSTS/E 


format by the following algorithm: 


e The system field is ignored 
e Delete protection is ignored 
e Extend protection is ignored 


e Read protection is mapped to RSTS/E read protection 
e Write protection is mapped to RSTS/E write protection 


Data Returned in RDB 


Mne-— Octal Octal 
monic Offset Offset 
, : 
s [seve reginin sewers eeks | 
sf nnn | 
mn _d 
adr+R.GSTS 


DSW Return Codes 


IS.SUC 
IK.PRI 


Successful completion. 
User does not have INSTAL privilege. 


TE.UPN Creation failed, examine FIRQB for details. 


Mne—- 
monic 


R.GID 
R.GSIZ 


R.GSTS 


is the status-flags word. Bit 15 is clear if the region already exists. 
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39.4 DTRG$ — Detach Resident Library 


5-18 DTRG$ 


The DTRG$ directive detaches the job from a previously attached resident 
library. Any windows mapped to the library by the calling job are unmapped and 
eliminated. If the specified library is a dynamic region marked for deletion when 
all users detach, the monitor checks if the region is no longer attached by any job. 
If so, the monitor deletes the region and releases the memory allocated to it. 
Privileges Required 


None 


Macro Call 
DTRG$ adr 
where: 


adr is the address of an 8-word area defining the library to be detached. The DTRG$ 
directive also returns information to this area. Two supplementary directives are 
available to define (RDBDF$) or define and fill (RDBBK$) such an 8-word area, 
called the Resident-Library Definition Block (RDB). 


Macro Expansion 


DTRGS RDBLK 
.BYTE 59.,2 ;DIC = 59., DPB SIZE = 2 WORDS 
.WORD RDBLK ; ADDRESS OF RDB 


Data Passed in RDB 


Mne— Octal Octal Mne— 
monic Offset Offset monic 


resident library ID 
LIITIETIITTTIT ATT 
LIA ATP ETAL A TATA AAA Td 


0 R.GID 


LIITIETTTTT TIAA T TT 
PEPPALULST LEAT AA LIAL LY 
| PAPITATA AAA TA 


adr+R.GID is the library ID the ATRG$ directive returns (at the same position in 
the RDB). 


Data Returned in RDB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
[mm] 
s[_ mm —_] + 
s[__ nnn | + 
{nnn _| 


adr+R.GSTS is the status flag, bit 14, that defines if any windows were unmapped 
as a result of this detach. 


Local Symbol Definitions 
D.TRBA Resident-Library Definition Block address (2) 


DSW Return Codes 


IS.SUC Successful completion. 


IE.NVR The library ID specified does not identify any library currently attached to the 
job. 
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5.8 ELAWS — Eliminate Address Window 


5-20 ELAW$ 


The ELAWS$ directive eliminates an address window that was created by the job, 
unmapping the window if necessary. ELAW$ frees the APRs used by the window 
and makes them available for creating another window or for expanding the user 
job image size. 

Privileges Required 


None 


Macro Call 
ELAW$ adr 
where: 


adr is the address of an 8-word area defining the window to be eliminated. The 
ELAWS$ directive also returns information to this. Two supplementary directives 
are available to define (WDBDF$) or define and fill (WDBBK$) such an area, 
called the Window Definition Block (WDB). 


Macro Expansion 


ELAWS WDBADR 
~- BYTE LLo e472 ;DIC=119., DPB SIZE=2 WORDS 
- WORD WDBADR 7; ADDRESS OF WDB 


Data Passed in WDB 


Mne— Octal Octal Mne- 
monic Offset Offset monic 
s(n | 
S| _| + 
[nnn | « 


adr+W.NID is the ID of the window to be eliminated (returned at the same location 
in the WDB by the CRAW$ directive). 


Data Returned in WDB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
1 PETTITTE TTT TTT TI 0 
3 Peele cesregageecees 2) 2 
5 TELA PIA LLATTL ITAA EET Ss 4 
7 TA LTITAVALIL I ALLA ELT | 6 
11 PADD EL ALT AT LEEAE TATA T 2 10 
13 VTTIATT TATA TA TT 12 
17 | ee Ge aa ae a pa whee: 16 
adr+W.NSTS is the status-flags word. Two bits in this word give the following 
information: 
WDBDF$, 
WDBBK$ 
Mnemonic Bit Meaning 
WS.ELW 13 =1 The window was successfully eliminated 
The window was not eliminated 
= 0 
WS.UNM 14=1 The window eliminated was mapped to a 
resident library and has been unmapped 
The window eliminated was not mapped; 
=0 no unmapping was done 


Local Symbol Definitions 
E.LABA Window Definition Block address (2) 
DSW Return Codes 


IS.SUC Successful completion. 


IE.NVW Bad window ID. It is either outside the range 1 to 22 or it does not match any 
window currently created for this job. 
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5.9 EXITS — Task Exit 


The EXIT$ directive stops execution of the calling job. Control passes to the job 
keyboard monitor at the keyboard monitor entry point PNEW (see Chapter 2). 
Any devices still open are reset; that is, closed without performing the usual 
clean-up operations. 


NOTE 


On exiting from the previously running program, the monitor drops 
any temporary privileges still in effect. 


The job keyboard monitor is the default keyboard monitor unless the job has 
issued the SET JOB/KEYBOARD_MONITOR command or executed the .RTS 
directive to establish a specific job keyboard monitor (see Chapter 3). 


Privileges Required 
None 

Macro Call 

EXIT$S [err] 
where: 


err is the error routine address. 


Macro Expansion 
EXITSS ERR 


MOV (PC)+,-(SP) ;PUSH DPB ONTO THE STACK 
- BYTE Delco ,DIC = 51., DPB SIZE = 1 WORD 
EMT Si ; TRAP TO THE EMULATOR 
JSR PC, ERR ;CALL ERROR ROUTINE 
NOTE 


Digital recommends the $S form for this directive for two reasons: 
first, only a one-word DPB is generated; second, no BCC instruction is 
generated for the $S form (or the $C form), since control never returns 
inline unless an error occurs. 


Thus, the $S form takes less space than the $ form/DIR$ combination. 
In addition, because the one-word DPB requires only one MOV instruc- 


tion, the $S form takes less space and no more execution time than the 
$C form. 


Local Symbol Definitions 


None 


DSW Return Codes 


IE.SDP DIC or DPB size is invalid. This occurs only if your program changes the first 
word of the DPB at execution time. 
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5.10 EXST$ — Exit with Status 


Like EXIT$, the EXST$ directive stops execution of the calling job. On exiting 


from the previously running program, the monitor drops any temporary privileges 


still in effect. In addition, EXST$ sets the job’s exit status. 


Control passes to the job keyboard monitor at the keyboard monitor entry point 
P.NEW (see Chapter 2). Any devices still open are reset; that is, closed without 
performing the usual clean-up operations. The monitor detaches any attached 
resident libraries, and eliminates any created address windows. 


NOTE 


The job keyboard monitor is the default keyboard monitor unless the 
job has issued the SET JOB/KEYBOARD_MONITOR command or 
executed the .RTS directive to establish a specific job keyboard monitor 
(see Chapter 3). 


Privileges Required 
None 

Macro Call 

EXST$ sts 

where: 


sts is the status value. DCL copies this data into the $SEVERITY and $STATUS 
variables (see the RSTS/E Guide To Writing Command Procedures). 


Macro Expansion 


EXSTS STATS 
- BYTE Zong ee ;DIC=29., DPB SIZE = 2 WORDS 
- WORD STATS ;BXIT STATUS WORD 


Local Symbol Definitions 


E.XSTS Exit status word (2) 
EX$WAR Warning status code 
EX$SUC Success status code 
EX$ERR Error status code 
EX$SEV Severe error status code 


DSW Return Codes 
No errors are possible with EXST$. 
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5.11 EXTKS$ — Extend Task 


5-24 EXTK$ 


The EXTK$ directive lets you increase the amount of memory allocated to the 
user job image. For compatibility with RSX-11M, the argument specified in the 
call indicates a positive or negative increment of 32-word blocks. However, the 
RSTS/E monitor actually allocates space for the user job image in 1K-word units. 
Thus, the RSX emulator keeps track of the user job image size as a number of 
32-word blocks. When an EXTK$ directive is executed, the emulator checks to 
see if the extension or reduction needs or frees one or more 1K-word blocks of 
memory. If so, the emulator directs the monitor to make the new allocation; if 
not, the current allocation remains. 


NOTE 


Do not use the .CORE directive (see Chapter 3) before an EXTK$ 
directive in the same program. The monitor executes the CORE 
directive directly, without the intervention (or knowledge) of the RSX 
emulator. If a .CORE executes before an EXTK$, the emulator has 
incorrect information on the current size of the user job image when it 
executed the EXTK$, and it bases the new allocation on the size before 
the .CORE was executed. 


You cannot extend the size beyond the least of the following: 


e The job’s private maximum size—A private job maximum size can be set by 
the system manager. 


e The system-wide maximum user job image size—Set by the system manager 
(see SWAP MAX, RSTS/E System Installation and Update Guide). 


e 32K-32 words—The maximum size allowed by the RSX emulator. 


You also cannot extend the size of the image into virtual address space used by 
an address window created for use with resident libraries (see CRAW$ directive). 


NOTE 


If I&D Space is in use, the size applies only to the D-Space of the task. 
The size of the I-Space is fixed at task load time. 


If there is not enough contiguous memory for the extension to be made where 
the job currently is in memory, the monitor swaps the user job image to disk and 
then returns it to memory at a location that can accomodate the new size. If no 
increment is given in the call, the emulator allocates the amount of space the job 
had initially, based on information built in at link time (with TKB); that is, before 
any EXTK$ was executed. 

Privileges Required 


None 


Macro Call 
EXTK$ [inc] 
where: 


inc is the number of 32-word blocks by which the task size is to be extended (positive 
value for inc) or reduced (negative value for inc). 


Macro Expansion 


EXTKS 40 

-BYTE 89.,3 ;DIC = 89., DPB SIZE = 3 WORDS 
- WORD 40 ;EXTEND 40(8) BLOCKS (1K WORDS) 
- WORD 0 ;RESERVED WORD 


Local Symbol Definitions 
E.XTIN Extend increment (2) 
DSW Return Codes 


IE.SUC Successful completion. 


IE.UPN The requested increment would have caused the user job image size to exceed 
that allowed (see previous discussion). The user job image size stays at the 
current size. 
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3-12 EXTM$—Extend Task by Mask 


5-26 EXTM$ 


This directive is similar to the EXTK$ directive. Both directives extend the task’s 
virtual address Data Space. However, when doing I&D-Space tasks, the EXTM$ 
directive unmaps the D-Space APRs (only) from libraries and includes them 

in the memory extension space, if allowed by the APR mask. This leaves the 
resident library mapped in I-Space only. In tasks built without I&D space (TKB 
/-ID option), the EXTM$ directive behaves exactly as the EXTK$ directive. 


During task memory expansion, RSTS/E maps resident libraries with both I&D 
Space APRs mapped identically; this is done by default. The EXTK$ directive 
does not override this mapping. If an attempt is made to extend into an APR 
used by the library, it will cause an error. 


The APR mask provides a method of reserving one or more APRs in the D-Space 
for resident library use. If, for example, a resident library is built with I-Space 
using APRs 5, 6, and 7 but all the needed D-Space is contained in APR 7, then by 
reserving APR 7 for the library, the task can extend its usable D-Space into APRs 
5 and 6. The task does this reservation by setting the APR 7 bit in the APR mask 
word in the EXTM$ call. 


If an EXTM$ extension of memory requires the use of an APR whose bit is set in 
the APR mask word, the system returns an error. 


The Task Builder has automated the process of constructing the APR mask word 
for the combination of libraries used in building the task. This data is available 
to the program at execution time. See the RSTS/E Task Builder Reference 
Manual for details. 


NOTE 


If 1&D Space is not turned on (/-ID), then all EXTM$ requests behave 
as though they are EXTK$ requests (that is, the APR mask word is 
Zero). | 


The lowest bit set above the current task D-Space determines the protection line 
above which a request will fail. For example, if only bit 3 is set, then APRs 3 
through 7 are protected even though bits 4 through 7 are not set. 


CAUTION 


Take care when using this call to remap D-Space away from a library. 
If the library is not coded in an I-only manner, the program is likely to 
behave unpredictably. 


Use EXTM$ to pass information to RSTS/E gathered by the Task Builder about 
the D-Space that the resident libraries associated with the task need. The task 
builder makes this link time data available at run time. 


If the program includes: 


-PSECT SSTSKP, D 
STSKP:: 
-PSECT [name of previous .PSECT] 


then the Task Builder fills the address at $TSKP with the inclusive OR of all the 
D-APR masks used by the program. At execution, the value of $TSKP can be 
used directly as the mask in the EXTM$ call by allowing the program to expand 
to the minimum size allowed for the particular library configuration in use. See 
the RSTS/E Task Builder Reference Manual on building resident libraries for 
details on the source values filled into $TSKP. 


Privileges Required 


None 


Macro Call 
EXTM$ [inc,mask| 


where: 


inc 


mask 


is the number of 32-word blocks by which the task size is to be extended (positive 
value for inc) or reduced (negative value for inc). 


is the APR mask word through which the caller passes information about those 
user D-Space APR registers protected from being expanded into by the task D- 
Space. This mask specifies which D-Space APRs are still available for resident 
library (or dynamic region) D-Space mapping. 

In the EXTK$ directive, this APR mask word is zero; it tells RSTS/E not to 
expand task D-Space beyond the base APR of the lowest mapped library or 
dynamic region. 

The APR mask word allows the user to control how the task extension is to work. 
Extension uses fall into three general categories listed in the following table. 


APR Mask 

Word Description 

0 The EXTM$ behaves as an EXTK$ on RSTS/E; that is, extension 
is only allowed up to the base of the first library APR. 

1 The EXTM$ behaves as an EXTK$ on RSX-11M/M-PLUS; that 


is, extension is allowed thru APR7 remapping the D-Space of any 
libraries. However, extension is not allowed past the beginning 
of a dynamic region or a window specifically mapped in D-Space. 


any other For all other values, the APR Mask Word acts like a memory 
protection flag. An EXTM$ request is not allowed to extend task 
D-Space into an APR that is above the current task D-Space and 
that the bit representing the APR is set (see the following list). 
It also is not allowed to extend past the beginning of a dynamic 
region or a window specifically mapped in D-Space. 


Macro Expansion 


EXTKS 
- BYTE 
- WORD 
- WORD 


Bit 7 Represents APR 7 <200> 
Bit 6 Represents APR 6 <100> 
Bit 5 Represents APR 5 <40> 
Bit 4 Represents APR 4 <20> 
Bit 3 Represents APR 3 <10> 
Bit 2 Represents APR 2 <4> 
Bit 1 Represents APR 1 <2> 
Bit 0 Must be set for EXTM$ <1> 

40,30 

89.,3 ;DIC = 89., DPB SIZE = 3 WORDS 

40 ;EXTEND 40(8) BLOCKS (1K WORDS) 

so ;MASK PROTECTS APRS 6 & 7 D-SPACE FOR LIBRARY 


Local Symbol Definitions 


E.XTIN 


Extend increment (2) 
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DSW Return Codes 


IE.SUC Successful completion. 


TE.UPN The requested increment would have caused the user job image size to exceed 
that allowed (see previous discussion). The user job image size stays at the 


current size. 
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5.13 FEADF$ — Define System Feature Labels 


The FEADF$ macro lets you define the system feature labels. 
Privileges Required 
None 


Macro Call 
FEADF$ 


This is purely a definition macro and therefore there are no results or errors. 
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5.14 FEATS — Test for System Feature 


5-30 FEAT$ 


The FEAT$ directive tests for the presence of a specific system software 
or hardware option, such as floating point hardware or the presence of the 
commercial instruction set. 


Macro Call 

FEAT$ sym 

where: 

sym is the symbol for the specified system feature. 
The supported system feature symbols are: 


Symbol Value Meaning 

FESEXT 1 22-Bit extended memory support 
FE$PLA 5 PLAS calls supported 

FE$LIB 18. Supervisor mode library support 

FE$UDS 37. User data space supported 

FESFMP 59. Fast mapping directive supported 
HF$UBM -1. Processor has UNIBUS mapping registers 
HF$EIS -2. Processor has Extended Instruction Set 
HF$QB -3. Processor has a Q-BUS backplane 
HF$DSP -4, Processor supports separate I & D spaces 
HF$CIS -8. Processor supports Commercial Instruction Set 
HF$FPP -16. Processor has NO floating point unit 


Macro Expansion 


FEATS FESFMP 
- BYTE LT Twp ;FEATS MACRO DIC, DPB size = 2 words 
» WORD FESFMP ;feature identifier 


Local Symbol Definitions 


FEAF Feature identifier 


DSW Return Codes 


IS.CLR Successful completion; feature not present (=0) 
IS.SET Successful completion; feature present (=2) 
TE.ADP Illegal DPB address 

TE.SDP Invalid DIC or feature identifier code 


NOTE 


The full list of RSX-11/M-PLUS feature identifiers is not supported on 
RSTS/E. 


5.15 GLUN$ — Get LUN Information 


The GLUN$ directive fills a 6-word buffer with information about a physical 
device unit to which a logical unit (LUN) is assigned. 


Privileges Required 


None 

Macro Call 

GLUN$ lun, buf 

where: 

lun is the logical unit number. 

buf is the address of the 6-word buffer to receive the information. 


Buffer Format 


Mne- Octal Octal Mne— 
monic Offset Offset monic 
7 | _seonddevin chars wert 


buf+0 is the name of the assigned device; two ASCII characters. This must be a 
valid physical device name. Exceptions are the logical device names OV and 
LB, which default to SY if they are not defined, and CL, which defaults to TT. 


buf+2 is the unit number of the assigned device. If this word is minus one, it 
indicates there is no unit number. If this word is zero or a positive number, it 
is a real unit number. 


buf+4 is the first device characteristics. The bit settings are: 
Bit Meaning When Set 


Record-oriented device 
Carriage-control device 
Terminal device 
Directory device 
Single-directory device 
Sequential device 

6-15 Reserved 


Settings for bits 0-5 are (in octal): 


01 = Card reader 

01 = Paper tape reader/punch 
02 = Line printer 

03 = Terminal 

10 = Disk 

40 = Magtape 
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5-32 


GLUN$ 


buf+6 is the privilege status. If this word is zero, it indicates the job is nonprivi- 
leged. If this word is eight, it indicates the job is privileged. 


buf+12 is the standard device buffer size to use for input or output on this device. 


Macro Expansion 


GLUNS 7, LUNBUF 

. BYTE 5,3 ;DIC = 5, DPB SIZE = 3 WORDS 
. WORD 7 ;LOGICAL UNIT NUMBER 7 

. WORD LUNBUF ; ADDRESS of 6-WORD BUFFER 


Local Symbol Definitions 


G.LULU Logical unit number (2) 

G.LUBA Buffer address (2) 

The monitor assigns the following offsets relative to the start of the LUN infor- 
mation buffer: 

G.LUNA Device name (2) 

G.LUNU Device unit number (1) 

G.LUFB Flags byte (not used in RSTS/E) (1) 

G.LUCW _ Four device characteristics words (8) 


DSW Return Codes 


IS.SUC Successful completion. 

TE.ULN Unassigned LUN. 

TE.ILU Invalid logical unit number (must be in range 1-14). 
TE.SDP DIC or DPB size is invalid. 


5.16 GMCR$ — Get MCR (CCL) Command Line 


The GMCR$ directive transfers an 80-byte CCL command line to the job. The 
program that processes an installed CCL command must contain code to analyze 
what you typed to invoke the file. The GMCR$ directive returns the command 
line you typed in an 80-byte buffer in the DPB. 


If the CCL command line is longer than 80 bytes, the first 79 bytes followed by 

a hyphen in position 80 is returned on the first call to GMCR$. A subsequent 
call returns the remaining portion of the command line. The maximum CCL 
command line length that can be retrieved via the GMCR§ call is 127. characters. 


This directive has no $S form. Because the DPB receives the CCL command line, 
the space must be allocated in read/write memory. 


Privileges Required 
None 

Macro Call 

GMCR$ 


Macro Expansion 


GMCRS 
- BYTE LZ hep ls ;DIC = 127., DPB SIZE = 41. WORDS 
- BLKW 40. ; 80-CHARACTER CCL COMMAND BUFFER 


Local Symbol Definitions 


G.MCRB CCL command buffer (80) 


DSW Return Codes 


+n Successful completion. The value n is the number of data bytes transferred 
(excluding the termination character). 


TE.AST Task was not run as a CCL command or the GMCR$ directive has already 
been executed. 


IE.SDP DIC or DPB size is invalid. 
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3.17 GPRT$ — Get Partition (Job) Parameters 
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The GPRT$ directive fills a 3-word buffer with partition parameters. For RSTS/E, 
a partition corresponds to the job area. | 


Privileges Required 


None 

Macro Cail 

GPRT$ [name], buf 

where: 

name is the partition name. Omit this parameter to get the actual job image size in 
buf+2. 

buf is the address of the 3-word buffer where information is to be returned. 


Buffer Format 


Mne—- Octal Octal Mne— 
monic Offset Offset monic 


1 | virtual base address (always 0 in RSTS/E) 0 G.PRPB 
3 user job image size in 32—word blocks 2 G.PRPS 


5 flags word (always 0 in RSTS/E) 4 G.PRFW 


name is the partition name. Omit name to get the actual job image size in buf+2. 


buf+2 is the partition size (user job image size in RSTS/E), expressed as a multiple 
of 32 words. If I&D Space is enabled, this reflects only the size of the D-Space 
of the task. If you give a partition name, the system SWAP MAX is returned, 
in 32-word units. 


buf+4 is the partition flags word. Always returned as zero, since all jobs are system- 
controlled in RSTS/E. (RSX-11M returns one for a user-controlled partition.) 


Macro Expansion 


GPRTS , DATBUF 

. BYTE 65.,4 ;DIC=65., DPB SIZE = 4 

. WORD 0,0 ;GENERATE 0 WORDS IF NO NAME 
. WORD DATBUF ; ADDRESS OF 3-WORD BUFFER 


Local Symbol Definitions 


G.PRPN Partition name (4) 
G.PRBA Buffer address (2) 


The monitor assigns the following offsets relative to the start of the buffer: 


G.PRPB Partition virtual base address (2) 
G.PRPS Partition size (2) 
G.PRF Partition flags word (2) 


DSW Return Codes 


Successful completion is indicated by carry clear, and the starting address of 
the partition is returned in the DSW (always zero in RSTS/E). Unsuccessful 
completion is indicated by carry set and the following code in the DSW: 


ID.SDP DIC or DPB size is invalid. 
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5.18 GTIM$ — Get Time Parameters 


5-36 GTIM$ 


The GTIM$ directive fills an 8-word buffer with the current day and time of day. 
All time values are stored as one-word binary integers. The value ranges (in 
decimal) are shown in the following diagram. 


Privileges Required 
None 


Macro Call 
GTIM$ buf 
where: 


buf is the address of an 8-word buffer. 


Buffer Format 


Mne- Octal Octal Mne-— 
monic Offset Offset monic 


year (since 1900); such as 78 =1978 


1 0 G.TIYR 
3 month (1-12); such os = January 2 G.TIMO 


G.TIBA+G.TICT Indicates a tick which is either 1/60th or 1/50th of a second, de- 
pending on the clock in use and/or the line frequency. Systems 
running with the KW11P clock at crystal speeds, rather than at line 
frequency, or 11/73, 11/83, 11/84, 11/93, or 11/94 systems with 800 
Hertz clocks, have a tick of 1/50th of a second. Otherwise, if the 
system is operating with a 60 Hz power line, a tick is 1/60th ofa 


second. 
Macro Expansion 
GTIMS DATBUF 
. BYTE 62052 ;DIC = 61., DPB SIZE = 2 WORDS 
» WORD DATBUF 7; ADDRESS OF 8-WORD BUFFER 


Local Symbol Definitions 


G.TIBA Buffer address (2) 


The monitor assigns the following offsets relative to the start of the buffer: 


G.TIYR 
G.TIMO 
G.TIDA 
G.TIHR 
G.TIMI 
G.TISC 
G.TICT 
G.TICP 


Year (2) 

Month (2) 

Day (2) 

Hour (2) 

Minute (2) 

Second (2) 

Clock tick of second (2) 
Clock ticks per second (2) 


DSW Return Codes 


Is.SUC 
IE.SDP 


Successful completion. 
DIC or DPB size is invalid. 
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9-19 GTSK$ — Get Task (Job) Parameters 


The GTSK$ directive fills a 16-word buffer with parameters for the task. As with 
partition in GPRT$, a task in the RSTS/E environment is equivalent to the job. 


Privileges Required 
None 


Macro Call 
GTSK$ buf 
where: 


buf is the address of the 16-word buffer to receive the parameters. 


Buffer Format 


Mne— Octal Octal Mne- 
monic Offset Offset monic 


1 task name 0 G.TSTN 
(2 words in RADS50 format) 

3 | 2 

5 | partition name 4 G.TSPN 
(2 words in RAD50 format) 

7 | 6 


run priority (0-255) | 
[pret romber —[_prosrarner somber | 
S220 777 


buf+0 is the task name. The name supplied for the TASK = name option at the 
time the task was built (linked) with TKB; otherwise, the file name of the 
file being run. 


15 14 G.TSPR 


G.TSPC 17 16 G.TSGC 


21 20 G.TSNL 
23 
25 


a 


26 G.TSVA 


31 30 G.TSVL 


33 32 G.TSTS 


35 34 G.TSSY 


buf+4 is the partition name specified for the PAR = name option at the time the 
task was built (linked) with TKB. If no such name was specified, the char- 
acters "GEN _" (GEN followed by three blanks), to indicate the general 
partition, the default system-controlled partition in RSX-11M. 


buf+14 is the run priority; may range from 0 to 255. This is the RSTS/E job priority 
plus 128. 
buf+16 is the programmer number of the user currently running the program. 
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buf+18 is the project number of the user currently running the program. 


buf+20 is the number of logical unit numbers (LUNs) currently assigned. 
buf+26 is the address of the SST vector table. If buf+30 = 0, this word is meaning- 


less. 


buf+30 is the length of the SST vector table, in words. If there is no SST vector 


table, this word is set to 0. 


buf+32 is the job size, in bytes. If I&D Space is enabled, this size reflects only the 


D portion of the task. 


buf+34 is the system in which the program/job/task is running: 


0 = RSX-11D 

1 = RSX-11M 

2 = RSX-118 

3=IAS 

4= RSTS/E 

5 = VAX/VMS 

6 = RSX-11M-PLUS 

7 = RT-11 

This value is always 4 on RSTS/E systems. 


Macro Expansion 


GTSKS DATBUF 
~-BYTE 63552 ;DIC=63., DPB SIZE = 2 WORDS 
- WORD DATBUF ; ADDRESS OF 16-WORD BUFFER 


Local Symbol Definitions 


G.TSBA Buffer Address 


The monitor assigns the following offsets relative to the buffer: 


G.TSTN Task name (4) 

G.TSPN Partition name (4) 

G.TSPR Priority (2) 

G.TSGC Programmer number (1) 

G.TSPC Project number (1) 

G.TSNL Number of logical units (2) 
G.TSVA SST vector address (2) 

G.TSVL Length of SST vector table (2) 
G.TSTS Size of space for user job image (2) 
G.TSSY System being run under (2) 


DSW Return Codes 


IS.SUC Successful completion. 
TE.SDP DIC or DPB size is invalid. 
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5.20 MAP$ — Map Address Window 


5-40 MAP$ 


The MAP$ directive maps a previously created address window to an attached 
resident library. In other words, MAP$ relates the virtual address range defined 
by a CRAW$ directive to actual locations in memory within a resident library 
that has been attached to the job by an ATRG$ directive. 


If the window specified is already mapped, it is unmapped from its previous 
actual memory locations and remapped to the new area. A job may map a 
maximum of seven address windows at any given time. 


Privileges Required 


None 


Macro Call 
MAP$ adr 
where: 


adr is the address of an 8-word area defining the window to be mapped. The MAP$ 
directive also returns information to this area. Two supplementary directives are 
available to define (WDBDF$) or define and fill (WDBBK$) such an area, called 
the Window Definition Block (WDB). 


Macro Expansion 


MAP $ WDBADR | 
. BYTE 121 gD ;DIC=121., DPB SIZE=2 WORDS 


Data Passed in WDB 


Mne— Octal Octal Mne- 
monic Offset Offset monic 
7 | a raciderit jibrany ID 6 W.NRID 
adr+W.NID is the ID of the window to be mapped (returned at the same location in 
the WDB by the CRAW$ directive). 
adr+W.NRID is the ID of the resident library to which the window is to be mapped 


(returned at offset R.GID in the RDB by the ATRG$ or CRRG$ direc- 
tive that attached the job to the resident library). 


adr+W.NOFF 


adr+W.NLEN 


adr+W.NSTS 


is the offset, in 32-word blocks, from the start of the library where the 
mapping is to begin. A value of zero for this word indicates that the 
window is to be mapped beginning at the first byte of the library. A 
value of one indicates that the window is to be mapped beginning at 
the 33rd word of the library (starting address +64), and so forth. The 
offset cannot indicate a starting address past the end of a library. 


is the length, in 32-word blocks, to be mapped to the library. This value 
cannot be greater than the size of the window defined in the CRAW$ 
directive with which the window was created. In addition, this value, 
combined with the offset value at adr+W.NOFF, cannot indicate an 
address beyond the end of the library. A value of zero for this word 
defaults to the size of the window or the space remaining in the library, 
whichever is smaller. 


is the access flag. When bit 1 (WS.WRT) is set, read/write access is 
allowed. A separate setting for access in MAP$ and in ATRG$ lets 
you attach to a library read/write and map a portion of the library 
read-only. You cannot, however, attach to a library read-only and then 
map to the library read/write. 


WDBDF$, 
WDBBK$ 
Mnemonic Bit Meaning 
WS.64B 8 =] The task’s permitted alignment bound- 
aries defined as 32 words. 
= 0 The task’s permitted alignment bound- 
aries defined as 256 words. 
WS.WRT 1 = Read/write access is desired 
= 0 Read-only access is desired 


Data Returned in WDB 


Mne- 
monic 


adr+W.NLEN 
adr+W.NSTS 


Octal Octal 
Offset Offset 


[nein 
sewn 
retteetiit_| EP TTTLIT EA ITAL DIALED | 


Mne- 
monic 


10 


12 W.NLEN 


14 W.NSTS 


16 


is the length, in 32-word blocks, mapped by the call. 


are the status flags. Bit 14 (WS.UNM) indicates, when set, if the 
window specified was unmapped before the new map. 


Local Symbol Definitions 


~M.APBA Window Definition Block address (2) 
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DSW Return Codes 


IS.SUC Successful completion. 

TH.ALG The offset and length specified are inconsistent; either the mapping attempted 
to go beyond the end of the library, or the length is greater than the created 
window. 

TE.PRI The mapping did not succeed because user privileges did not allow the access 
desired. 

TE.NVW Hither the resident library ID or the address window ID is incorrect. (That is, 


the job is not currently attached to the specified resident library, or no address 
window has been created with the specified window ID.) 


5.20.0.1 


5-42 MAP$ 


Fast-Mapping Facility 


You may want to use the fast-mapping facility instead of the MAP$ directive. 
It enhances performance and is compatible with the fast-mapping facility of 
RSX-11M-PLUS. The RSTS/E RSX emulator also provides the following features: 


e The Task Builder /FM switch. 
°¢ The TFEA$ RSX monitor call can tell a program if fast-mapping is enabled. 


¢ The SET and .CLEAR monitor calls allow a task to enable and disable 
fast-mapping. 


You can use fast-mapping if your program does not use any IOT instructions 
except to perform the fast-map operations. To use the fast-mapping facility, 
set parameters as shown in the following calling sequence, then issue an IOT 
instruction: 


Calling Sequence 


RO parameter 1 see table of APR parameter values 

Rl parameter 2 offset field, 32 decimal words from library base 

R2 parameter 3 optional length specification (if used, bit 15 
in RO must =1) 

LOT calls the monitor to execute mapping 


Returned Data 


RO Status IS.Suc if successful 
IE.TIS or IE.ALG if unsuccessful 
R2 length mapped if successful length actually mapped in slivers 


R1 & R3 indeterminate 


Table of Parameter Values 


f 

Base If No Length a 
Space APR Given Given 
User-I 0 APR I-0 cannot 

be changed 

User-I 1 000010 100010 
User-I 2 000020 100020 
User-I 3 000030 100030 
User-I 4 000040 100040 
User-I 5 000050 100050 
User-I 6 000060 100060 


Space 


User-I 


User-D 


User-D 
User-D 
User-D 
User-D 
User-D 
User-D 
User-D 


Base 
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If 


If No Length Length 
Given Given 
000070 100070 

APR D-0 cannot 
be changed 
000110 100110 
000120 100120 
000130 100130 
000140 100140 
000150 100150 
000160 100160 
000170 100170 


The fast-mapping facility has the following requirements: 


e The fast-mapping facility can modify only the map field (FQSIZE) and, 
optionally, the length to the map field (FQBUFL). 


e The interface to the fast-mapping facility is designed for speed, not for ease of 
programming. It may be harder to debug a task using fast-mapping than one 
using the .PLAS directive. The only validation fast-mapping does is to protect 
the operating system and its data structures 


e The interface uses the IOT instruction. Tasks that use fast-mapping cannot 
use the IOT instruction for any other purpose. 


e The interface uses registers to pass parameters instead of using a FIRQB. 
This means that the MACRO-11 programmer must be careful about register 


use when fast-mapping. 


Examples 


Change the window offset in an I-Space library: 


MOV 
MOV 


IOT 
TST 
BMI 


#60, RO 


#200,R1 


RO 
ERROR 


;I-Space window in APR 6 

;offset 4K words from the beginning of library 
7;R2 not used 

;do the re-map 

yany errors? 

;if minus yes, otherwise ok 


Change the D-Space window offset and the actual window length: 


MOV 
MOV 
MOV 
IOT 
TST 
BMI 


#100150, RO 


#400,R1 
#500,R2 


RO 
ERROR 


;D-Space window in APR 5, length to be given 
;offset 8K words from library base 

;length to be 10K words (use APR 5,6 &7) 
sissue instruction 

pany errors? 

;if minus yes, otherwise ok 
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5.21 MSDS$—Map Supervisor Mode D-Space 


5-44 MSDS$ 


The MSDS$ directive allows a task to change the mapping of its supervisor mode 
D-Space APRs. This directive can also provide information about the current 
mapping of the task’s supervisor mode D-Space APRs, or about a library’s current 
mode. 


Normally, when supervisor mode library code is executing, the supervisor mode 
I-Space APRs map supervisor mode instruction space, and the supervisor mode 
D-Space APRs map the User mode D-Space. However, code that resides in a 
supervisor mode library may need to use its instruction space as data space for 
such items as error messages or other text. The Map supervisor Data Space 
directive allows such code to overmap the supervisor D-Space and the supervisor 
I-Space on an APR by APR basis. This overmapping can be used with tasks built 
using separate I-Space and D-Space mapping. 


The Map Supervisor D-Space directive allows the task to specify a 7-bit mask that 
determines which space each supervisor D-Space APR will use. The mask value 
contains one bit for each APR beginning at APR1. Supervisor mode D-APRO must 
overmap user mode D-APRO at all times and therefore is not included in the 
mask value. 


On the return from the MSDS$ call, the current supervisor mode D-Space 
mapping mask is returned along with the high byte (mode bits) of the PSW. If 
bit 15 of the mask value is set to 1 on the call, no change occurs to supervisor 
mapping but existing mapping is returned. 


The MSDS$ call is designed to be executed from within the library whose 
mapping it alters. This allows a library to determine its current mode from the 
PSW mode bits returned. Further, if the MSDS$ call is issued from user mode 
rather than supervisor mode, no mapping change occurs. The call simply returns 
the mapping data and PSW contents. Note that the MSDS$ call returns only 
the supervisor mode mapping status. If the library is in user mode, no useful 
mapping data is returned. Normally, a library in user mode will have its D-Space 
already mapped to user mode D-Space unless the task builder or the program has 
taken some overt action to re-map the D-Space. 


Digital recommends that you place all required data at the highest addresses in 
the library. Not only does this remove it from the APRO restriction in supervisor 
mode, but also allows the library to make proper use of the EXTM$ directive (see 
the RSTS/E Task Builder Reference Manual) when used in user mode. 


Privileges Required 


None 


Macro Call 
MSDSS' mask 


where: 


mask is a 7-bit APR mask plus an action flag, formatted as follows: 


Bit Meaning 
0-7 Set to 0 on input. Set to PSW high-order byte on return. 
8 APR 1 mapping switch. If 1, then supervisor mode D-Space equals 


supervisor mode I[-Space. 


9 APR 2 mapping switch. If 1, then supervisor mode D-Space equals 
supervisor mode I-Space. 


10 APR 3 mapping switch. If 1, then supervisor mode D-Space equals 
supervisor mode I-Space. 


11 APR 4 mapping switch. If 1, then supervisor mode D-Space equals 
supervisor mode I-Space. 


12 APR 5 mapping switch. If 1, then supervisor mode D-Space equals 
User mode D-Space. 


13 APR 6 mapping switch. If 1, then supervisor mode D-Space equals 
supervisor mode I-Space. 


14 APR 7 mapping switch. If 1, then supervisor mode D-Space equals 
supervisor mode I-Space. 


15 Action flag. If 0, then set mapping. If 1, then report current supervi- 
sor mode D-Space mapping (no changes). If issued from user mode, 
flag is forced to 1. 


Macro Expansion 
-MACRO MSDSS mask 


.BYTE ZOLee2 ;MSDSS DIC code, DPB size= 2 words 
» WORD mask 
- ENDM 


Error codes 


IE.SDP DIC or DPB size is invalid 
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Example 


Poe 


“e “e Se 


TST 
BPL 


MSDSSS 
MOV 
MOV 


BIS 
MSDSSS 


MOV 
CALL 


MOV 
MSDSSS 


+ 


“eae “Ne Ne 


MESSAG: .ASCIZ 


(RO) 
DATAOK 


#100000 
SDSW, RO 
RO,-(SP) 


#400,R0 
RO 


#MESSAG, R1 
OUTMSG 


(SP) +, RO 
RO 


/Exrror in data/ 


This is sample code that might exist in a supervisor library 
for the purpose of printing error messages. 


;test some piece of user data 
;skip next if data ok 


rget current mapping state 


;save for future restoration 


;update mask to map APR1 to super I 
;change the mapping 


;pointer to error message which is data 

;call a routine in super mode to output 
;text data message 

rget back the original mapping state 

rnow back to the original state 


Somewhere in APR 1 of supervisor library: 


5.22 QIO$ and QlIOW$ — Queue I/O Request (and Wait) 


The QIO$ and QIOW$ directives do non-file-structured I/O. In the RSX emulation 
mode environment, QlO$ and QIOW$ do the same thing. I/O is synchronous in 
this environment. That is, you cannot request I/O, do other processing, and get 
an interrupt when the I/O completes. In RSX emulation mode, control returns to 
the program only when the I/O is complete. 


As non-file-structured implies, the QIO$ and QIOW$ directives are useful for I/O 
on a terminal, card reader, or line printer. 


Privileges Required 


See discussion 


Macro Call 
QIO$ 
QIOW$ fne,lun,lefn],[pril,{isb],[ast][,par] 
where: 
fne is the I/O function code: 


IO.ATT Attach. In RSTS/E, opens the device specified by the logical unit 


number (lun). 


IO.DET Detach. In RSTS/E, closes the device specified by the logical unit 


number (Jun). 


IO.RAL For terminals only, performs a read in ODT mode (see .TTDDT in 
Chapter 3). 


TO.RLB Read. IO.RLB and IO.RVB do the same thing in RSTS/E. The 
IO.RVB actions performed depend on the device (see the section "Format and 
Description by Function Code"). 


TO.WAL For terminals only, performs a write in binary mode (see RECORD 
4096% for terminal output, RST'S/H Programming Manual). 


IO.WLB Write. IO.WLB and IO.WVB do the same thing in 


IO.WVB RSTS/E. The actions performed depend on the device (see the section 
"Format and Description by Function Code’). 


lun is the logical unit number; defines the device for which the I/O operation is to be 
performed. Must have been previously defined with an ALUN$ directive. 

efn is the event flag. (The RSX emulator ignores this parameter.) 

pri is the priority. (The RSX emulator ignores this parameter. ) 

tsb is the /O status block. Address of a 2-word buffer to which information is 


returned about the outcome of the I/O operation. The contents vary according to 
the function code and device, as the following describes. 


ast is the asynchronous exception address. (The RSX emulator ignores this parame- 
ter. ) 
par is the parameter list. Of the form <p1,p2I[,,,,p3]> for RSTS/E users. Form and 


meaning varies according to function code and device, as the following describes. 
Format and Description by Function Code 
{ QIO$ 


IO. ATT Junl,,,isb] 
QIow$ 
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Opens the device specified by the logical unit number (dun). Status information 
is returned to the 2-word buffer at address isb. If the device is restricted, this 
function requires DEVICE privilege. 


QIO$ 
| 10.DETlunL,,,isb] 
QIow$ 


Closes the device specified by the logical unit number (lun). Status information is 
returned to the 2-word buffer at address isb. This function does not require any 


privileges. | 
QIO$ IO.RLB 
,lun,,,lisb],,<stadd, size [,,,block]> 
QIow$ IO0.RVB 


For record-oriented devices in the RSX-11M environment (see GLUN$), IO.RLB 
and IO.RVB return a record (a line on a terminal, card on a card reader, record 
on a paper tape reader). The data is read into the buffer whose starting address 
is defined by stadd and whose length in bytes is defined by size. The amount 
of data read never exceeds the buffer size. If the buffer size is smaller than the 
record, the next IO.RLB or IO.RVB for that Jun reads another buffer-full. The 
block parameter is omitted for these devices. 


For disk, IO.RLB and IO.RVB fill the buffer whose starting address is defined 
by stadd and whose length in bytes is defined by size. The read begins with the 
device cluster number specified by the block parameter. If block is omitted or 0, 
sequential reads are performed and the next read begins with the next device 
cluster. The buffer size should be a multiple of the device cluster size for the disk 
(see Appendix B). 


NOTE 


Only jobs with the necessary privileges can do non-file-structured disk 
I/O. RDNFS privilege is required for read-only and WRTINFS privilege 
is required for read/write non-file-structured disk I/O. 


For all devices, the isb parameter is the address of a 2-word buffer to which 
status information on the read is returned. If isb is omitted, no such status is 


returned. 
QIO IO.WLB 
,lun,,,Lisb],,<stadd, size[,ufc]> 
QIow$ IO.WVB : 


For record-oriented devices in the RSX-11M environment (see GLUN$), IO.WLB 
and IO.WVB write the contents of the buffer to the device specified by the logical 
unit number (lun). The starting address for the buffer is defined by stadd, and 
the length in bytes is defined by size. For record-oriented and carriage-controlled 
devices, the ufc parameter specifies an action to be performed after the buffer 
contents are written. (The ufc parameter is a vertical format control character for 
terminals and line printers.) 
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Table 5-2 lists the values for ufc and the actions taken. The ufc parameter is 
omitted for non-carriage-controlled devices. 


Table 5-2: Vertical Format Control Characters 


naan enn TTT atta 


Octal 

Value Character Meaning 

Ess est a a a 

040 blank Single space—Output a line feed, print the contents of the 
buffer, and output a carriage return. Normally, printing 
immediately follows the previously printed line. 

060 0 Double space—Output two line feeds, print the contents 
of the buffer, and output a carriage return. Normally, the 
buffer contents are printed two lines below the previously 
printed line. 

061 1 Page eject—Output a form feed, print the contents of the 
buffer, and output a carriage return. 

053 + Overprint—Print the contents of the buffer and output a 
carriage return. Normally overprints the previous line. 

044 $ Prompting output—Output a line feed and print the con- 


tents of the buffer. This mode of output is intended for use 
with a terminal on which a prompt message is output and 
input is then read on the same line. 


000 null Internal vertical format—Print the buffer contents without 
adding vertical format control characters. In this mode, 
more than one line of guaranteed contiguous output can be 
printed for each I/O request. 


i 


For disk, IO.WLB and 10.WVB write the contents of the buffer to disk, beginning 
at the device cluster number specified by the block parameter. If block is omitted, 
sequential writes are performed. The next write (for sequential writes) begins 
with the next device cluster. The buffer size must be a multiple of the device 
cluster size. 


NOTE 


No job can write to disk in non-file-structured mode while any other 
user is accessing the disk. 


For all devices, the isb parameter defines the starting address of a 2-word buffer 
to which status information on the write is to be returned. If you omit isb, no 
such status information is returned. | 


Contents of I/O Status Buffer 


The general format of the information returned to the 2-word status buffer 
defined by tsb is: 


(terminal I/O code) | general I/O code 


number of bytes read or written 


The first word contains information on the success or failure of the I/O operation 
requested. As with ¢$DSW, you can use mnemonic codes to test this word. The 
Task Builder resolves the mnemonics automatically. 
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For all devices and operations except terminal reads, you test the low-order byte 
of the first word to determine the I/O status code. Successful terminal reads 
provide additional information on what character terminated the line typed at the 
terminal. For terminal reads, you test the low-order byte first to see if the read 
was successful (IS.SUC). If it was, you can then test the entire first word to find 
out if the line was terminated with a carriage return (IS.CR) or an ESC character 
(IS.ESC), which is called ALTMODE on some terminals. 


The second word of the block contains the number of bytes read or written, if the 
read or write was successful. No information is returned in this word for IO. ATT 
and IO.DET operations. 


The following section describes the I/O return codes. IS.CR and IS.ESC are 
full-word values; the others are tested by the low-order byte only. 


NOTE 


The RSX emulator does the requested I/O operation using the non-file- 
structured OPNFQ subfunction of CALFIP, the CLSFQ subfunction 

of CALFIP, .READ, and .WRITE. It does not clear the FIRQB or XRB 
when it returns control to the user program. The codes given in square 
brackets [] are the RSTS/E errors that are returned to the emulator. 
You can do further checking in the case of IE.BAD, for example, by 
checking byte 0 of the FIRQB. 


Return Codes 


IS.SUC Successful completion of I/O operation. For terminal reads, you can determine 
the terminating character of the line by testing the full first word of the /O 
status buffer for: 


IS.CR The terminal line was terminated with a carriage return/line 
feed combination. (The terminating characters are not included 
in the character count in the second word. They do appear in the 
input buffer.) 


IS.ESC The terminal line was terminated with an ESC (called 
ALTMODE on some terminals). (The terminating character 
is not included in the character count in the second word. It does 
appear in the input buffer.) 


TE.BAD This code is returned by the RSX emulator when an error occurs on the 
I/O operation that did not fit into any of the error categories diagnosed. To 
determine the RSTS/E error, examine byte 0 of the FIRQB. 


TE.DAA An open (IO.ATT) was attempted for a device that this job has already opened. 
The device must be closed (IO.DET) before it can be opened again. [NOTCLS] 

IE.DNR Some hard device I/O error occurred (a read for an off-line device, a write for 
a physically write-locked device, and so forth). [HNGDEV] 


TE.EOF An end-of-file (EOF) mark, record, or control character (Ctrl/Z for terminals) 
was recognized on a read operation. [EOF] 


TE.EOT No more room is available on the device for a write operation (end of pa- 
per tape, end of magtape, not enough disk space available, and so forth). 
[NOROOM] 

TE.PRI Privilege violation. A job with insufficient privileges attempted to read or 


write to disk while the disk was in use. [PRVIOL] 
TE.NLN A close (IO.DET) was attempted for a device that was not open. [NOTOPN] 


TE.RSU Shareable resource in use. The device is not available; it is assigned to 
another user. [NOTAVL] 


5-50 QIO$ and QIOW$ 


IE.VER Unrecoverable error, such as parity error, bad card column, and so forth. 


[DATERR] 


Macro Expansion 


QIos IO.RVB,7,,, 1OSTAT, , <IOBUFR, 80.> 

.BYTE 1,12. ;DIC=1, DPB SIZE = 12. WORDS 

. WORD IO.RVB ;FUNCTION CODE FOR READ 

. WORD 7 ;LOGICAL UNIT NUMBER 7 

. BYTE 0,0 :EFN,PRI IGNORED IN RSTS/E 

. WORD IOSTAT :I1/O STATUS BUFFER 

. WORD 0 :AST IGNORED IN RSTS/E 

. WORD IOBUFR : BUFFER ADDRESS 

. WORD 80. :BYTE COUNT = 80. 

. WORD 0 ;NO VFC NEEDED FOR READ 

. WORD 0 :THIS PARAM. IGNORED IN RSTS/E 
. WORD 0 >THIS PARAM. IGNORED IN RSTS/E 
. WORD 0 :NO BLOCK FOR THIS INVOCATION 


The expansion for QIOW$ is the same except that the DIC = 3. 


Local Symbol Definitions 


Q.IOFN I/O function code (2) 

Q.IOLU Logical unit number (2) 
Q.IOEF Event flag number (1) 
Q.IOPR Priority (1) 

Q.IOSB Address of I/O status block (2) 
Q.IOAE AST address (2) 

Q.IOPL Parameter list (6 words) (12) 


DSW Return Codes 


IS.SUC Successful completion. 

IE.LUN Unassigned logical unit number (Jun). Use ALUN$. 

TE.ILU Invalid logical unit number (lun). Must be in the range 0 to 14. 
IE.SDP DIC or DPB size is invalid. 
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5.23 RDBBK$ and RDBDF$—Define and Fill RDBs 


Two directives are available for use with resident library definition blocks (RDBs): 
RDBDF$ and RDBBK$. 


The RDBDF$ directive assigns literal values to the offsets and status bit 
mnemonics shown for the RDB areas for the ATRG$ and DTRG$ directives. You 
can use these mnemonics to reference offsets and bit values in an RDB you have 
allocated space for in your program. 


The RDBBK$ directive defines these offsets and, in addition, generates code to 
allocate space for the RDB and fills it with values you specify in the call. 
Privileges Required 

[Not applicable] 


Macro Call 


RDBBK$ _ size,libnam,,status, pricde (for read/write access) 
or 


RDBBK$ _ size,libnam,,status,prtcde (for read-only access) 


where: 

size is the size of the dynamic region to create, if defining a RDB to create a 
dynamic region. 

libnam is the name of the resident library to be attached or the dynamic region to 
be created. 

status is the region status to be placed in the RDB. The following are defined 
status bits: 

RS.ATT When creating a dynamic region, setting this bit indicates 
that the user wants the region attached on creation. Note 
that RSTS/E forces this bit to be set when creating an un- 
named dynamic region. 

RS.MDL When creating a dynamic region, setting this bit indicates 
that the region is automatically removed on the last detach. 
Note that RSTS/E forces this bit to be set when creating an 
unnamed dynamic region. 

RS.NDL When creating a dynamic region, setting this bit indicates 
that the region is not automatically removed on the last 
detach. Note that RSTS/E forces this bit to be set when 
creating an unnamed dynamic region. 

RS.RED Map with read-only access to library. (for ATRG$) 

RS.WRT = Map with read/write access to library. (for ATRG$) 

prtcde is the protection code (in RSX format) of the dynamic region to be created. 


Macro Expansion 


RDBBK$ SIZE,DATLIB, ,<RS.WRT>,167000 
.WORD 0 

.WORD SIZE 

-RAD50 /DATLIB/ 

.WORD 0 

.WORD 0 

.WORD RS.WRT 

.WORD 167000 


(RS.WRT is assigned to a literal value of two, so bit i: is set in the seventh word 
of the RDB, requesting read/write access.) 
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In addition, all the offsets necessary to reference the data returned in the RDB 
by ATRG$ or DTRG$ are generated. For example, you can use the mnemonic 
RS.UNM to test bit 14 of the word at offset R.GSTS in the RDB after execution of 
a DTRG$ directive. RS.UNM is assigned to a literal value of 40000 (octal) by the 
RDBBK$ directive. 
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5.24 SCCAS$S — Specify Control/C AST 


5-54 SCCA$S 


The SCCA$S directive (actually, a macro) lets you specify an address to which 
control is to be transferred if the user types a Ctrl/C while the program is 
executing. Only the $S form is allowed, because no DPB is ever generated. The 
SCCA$S directive is unique to the RSTS/E environment; no similar directive 
exists for the RSX-11M operating system. 


The SCCA$S expands to code that takes the address specified and stores it in 
location 24 (part of the first 512 bytes of memory used by the run-time system; 
see Chapter 4). The RSX run-time system checks this location when a Ctrl/C 
asynchronous exception occurs, and if it is nonzero, clears the word and transfers 
control to the location that was specified. If this word is zero, the RSX run-time 
system falls back to its own processing of Ctrl/C exceptions. Thus, SCCA$S is a 
one-time operation; you must reset the handler as part of the exception-processing 
routine, if desired. 


Your routine can handle the Ctrl/C in any way it sees fit. The Ctrl/C routine 
should be exited with the use of the SSTX$ macro. This will return control back 
to the point where it left off at the time of the exception. If the task is going to 
use a library in supervisor mode, the SSTX$ exit is required. 


The trap service routine for SCCA$S may be in either user space or supervisor 
space. This is determined in bit 0 of the service vector. If bit 0 is set, the service 
routine is in supervisor space; if bit 0 is clear, the service routine is in user space. 


Privileges Required 


None 


Macro Call 
SCCA$S [arg] 
where: 


arg contains the address (usually specified in the form "#addr") to which control 
passes if the user enters a Ctrl/C combination at the job’s terminal. Word 24 is 
cleared, indicating that the RSX run-time system is to handle such traps. 


Macro Expansion 


SCCASS #CTRAP 
MOV #CTRAP, @#24 


If you omit the address, the expansion is: 


SCCASS 
CLR Q#24 


Local Symbol Definitions 


None 


DSW Return Codes 


None. (SCCA$S does not execute an EMT; control does not pass to the RSX 
emulator when SCCAS$S is executed.) 


5.25 SFPA$ — Specify Floating-Point-Processor Exception 
| Address 


The SFPA$ directive tells the RSX emulator one of two things: 


The job wants to handle FPP exceptions itself. The RSX emulator passes 
control to the address specified in the directive when such an asynchronous 
exception occurs. 


The FPP available on all PDP-11 processors that can run RSTS/E, except the 
PDP-11/35 and 40. The FPP executes concurrently with the PDP-11 central 
processor. Thus, an error in the FPP unit occurs asynchronously with the 
execution of the PDP-11 CPU. 


The job does not want to handle FPP exceptions. The address is omitted in 
the directive. In this case, if an FPP exception occurs, the RSX emulator 
aborts the job, and displays the error message ??Reserved instruction trap on 
the job’s terminal (TI:). 


If you specify an address in the SFPA$ directive, control passes to the address 
when an FPP exception occurs. The stack has the following information: 


SP —> FEA 


FEC 

(DSW) at the time the exception occurred 
(PC) at the time the exception occurred 

(PS) at the time the exception occurred 

word to which SP pointed before the exception 


Your routine can process the exception in any way it sees fit. To exit from the 
exception-handling routine, pop the FEA and FEC from the stack and issue an 
ASTX$ directive. 


Privileges Required 


None 


Macro Call 
SFPA$ [add] 


where: 


add 


is the address to which control passes when an FPP exception occurs. 


Macro Expansion 


SFPAS FLTAST 
- BYTE a Bales ae ;DIC = 111., DPB SIZE = 2 WORDS 
- WORD FLTAST 7;ADDRESS OF FLOATING POINT AST 


Local Symbol Definitions 
S.FPAE Exception handler entry address (2) 


DSW Return Codes 


IS.SUC Successful completion. 
IE.SDP DIC or DPB size is invalid. 
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5.26 SPND$S — Suspend 


The SPND$S directive instructs the system to suspend the execution of the 
issuing program. A program can only suspend itself; it cannot suspend any other 
program. The program is restarted when the user types anything terminated by 
a RETURN or other delimiter (for example, LINE FEED). 


NOTE 


RSTS/E implements this directive using the .READ directive to the 
job’s terminal (channel 0). Thus, if you are using special terminal 
modes (binary input, echo control, and so forth), the SPND$S directive 
clears these modes. 


Because this directive requires only a 1-word DPB, Digital recommends the $S 
form of the macro. It requires less space and runs with the same speed as the 
DIR$ macro. 


Privileges Required 

None 

Macro Call 

SPND$S [err] 

where: 

err is the error routine address. 


Macro Expansion 
SPNDS$S ERR 


MOV (PC)+,-(SP) ;PUSH DPB ONTO THE STACK 

- BYTE 45.,1 ;SPNDS$S MACRO DIC, DPB SIZE=1 WORD 
EMT 377 ; TRAP TO THE EMULATOR 

BCC ~ +6 *7BRANCH IF DIRECTIVE SUCCESSFUL 
JSR PC, ERR ,;OTHERWISE, CALL ROUTINE "ERR" 


Local Symbol Definitions 


None 


DSW Return Codes 


IS.SPD Successful completion; that is, the task was suspended. 
TE.ADP Part of the DPB is out of the issuing task’s address space. 
IE.SDP DIC or DPB size is invalid. 
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5.27 SSTX$ — System Synchronous Trap Exit 


You can use the SSTX$ directive to terminate a routine that handles a syn- 
chronous system trap such as BPT and Ctrl/C exceptions, only if the program has 
indicated its intention to handle such traps with a SVTK$ or SVDB$ directive. 
When the SSTX$ is issued, control is returned to the point where the program 
left off at the time of the trap. 


If the task also uses supervisor mode libraries, then the SSTX$ is the required 
exit from any synchronous trap service routine. There is no equivalent directive 
in RSX-11/M-PLUS. 


If the trap was a memory protection violation, the service routine must remove 
the additional memory register information from the stack before issuing the 
SSTX$ directive. 


Privileges Required 


None 
Macro Cail 
SSTX$ 
Macro Expansion 
TST 2(SP) ;Is this a user or super return? 
BPL 108 ;Super! 
RTI ;User 
10S: CSM #0 ;So, return to supervision mode via Digital Standard. 


Local Symbol Definitions 
None 


DSW Return Codes 


None. (SSTX$ does not execute an EMT; control does not pass to the RSX 
emulator when SSTX$ is executed.) 


NOTE 


The SSTX$ call, when used with supervisor mode, is supported only 
when the Digital-supplied Supervision Linkage modules are used. 
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9.28 SVDB$ — Specify SST Vector Table for Debugging Aid 


The SVDB$ directive, like the SVTK$ directive, defines a table of addresses to 
which control is to pass when certain synchronous exceptions occur. When a 
synchronous exception occurs, the RSX emulator first checks the table defined 
with SVDB$ to see if an address has been specified for that trap. If so, control is 
passed to that address. If not, the emulator then checks the table defined with 
SVTK$ (if any). 


In other words, the SVDB§$ sets up an SST vector table whose entries, if 
nonzero, override (but do not destroy) any SST vector table entries defined with 
SVTK$. The SVDB$ directive is useful within a debugging routine that uses 
BPT instructions (for example, to set breakpoints). With SVDB$, the debugging 
routine can divert breakpoint traps to itself, regardless of SVTK$ directives in 
other modules of the job. 


For example, the Octal Debugging Tool (ODT) object module uses the SVDB$ 
directive to divert exceptions to itself, regardless of what may have been 
requested with SVTK$ in other modules. This makes it possible to debug 
without changing your source code; you can link with ODT, use ODT to insert 
breakpoints, test and debug, and when finished, relink without ODT. Note that 
it is not necessary to change source code to debug, only to relink: the SVDB$ 
directive makes this possible. 


NOTE 


The ODT object module (the file ODT.OBJ) can be linked to user 
modules with the RSTS/E Task Builder (TKB) using the /DA switch, as 
described in the RSTS/E Task Builder Reference Manual. ODT.OBJ is 
different from ODT.BAC, which is a BASIC-PLUS utility in RSTS/E. 
The commands and syntax for ODT.OBJ are described in the RSX/IAS 
ODT Reference Manual. 


To avoid interfering with ODT, do not use the SVDB$ directive in a 
user program. 


See also Chapter 3, the section "Trap Handling with Supervisor Mode," which is 
the last section in the chapter. 


Privileges Required 


None 


Macro Call 
SVDB$ [adr,len] 
where: 


adr is the address of the SST vector table. If adr and len are both omitted, any SST 
vector table previously defined with an SVDB$ directive will be deassigned; that 
is, the emulator will not check for SVDB$ addresses. (A previously executed 
SVTK$ remains in effect.) 


len is the length of the SST vector table, in words. You can specify up to eight 
addresses. If you want to use only the third, you could save space by using a len 
of three, rather than a len of eight and filling the last five words of the buffer 
with zeros. Specifying a length greater than eight has the same effect as a length 
of eight. 
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Vector Table Format 


A nonzero value for a word is the address to which control passes when that 
particular exception occurs. A zero value for a word indicates that you have no 
interest in handling that exception. Should such a exception occur, the emulator 
checks the vector table assigned by SVTK$, if any. If there is no SVTK$ vector 
table, the emulator aborts the job and displays an error message at the job’s 
terminal. 


Octal Octal 
Offset Offset 


. . 
, : 
. :, 
) 
Macro Expansion 
SVDBS SSTTBL, 3 
- BYTE LOS 673 ;DIC=103. ,DPB SIZE = 3 WORDS 
- WORD SSTTBL ; ADDRESS OF SST TABLE 
- WORD 3 ;SST TABLE LENGTH = 3 WORDS 


Local Symbol Definitions 


S.VDTA Table address (2) 
S.VDTL Table length (2) 


DSW Return Codes 


IS.SUC Successful completion. 
TE.SDP DIC or DPB size is invalid. 
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5.29 SVTK$ — Specify SST Vector Table for Task 
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The SVTK$ directive, like the SVDB$ directive, defines a table of addresses 

to which control passes when certain synchronous exceptions occur. When a 
synchronous exception occurs, the RSX emulator first checks to see if a similar 
table has been defined for this job with an SVDB$ directive. If so, any nonzero 
entries in that table override those defined with an SVTK$ directive. 


See also Chapter 3, the section "Trap Handling with Supervisor Mode," which is 
the last section in in the chapter. 


Privileges Required 


None 


Macro Call 
SVTK$ [adr,len] 
where: 


adr is the address of the SST vector table. If you omit both adr and len, any SST vec- 
tor table previously defined with an SVTK$ directive is deassigned. (A previously 
executed SVDB$ remains in effect.) 


len is the length of the SST vector table, in words. You can specify up to eight 
addresses. If you want to use only the first five, you could save space by using a 
len of five, rather than a len of eight and filling the last three words of the buffer 
with zeros. Specifying a length greater than eight has the same effect as a length 
of eight. 


Vector Table Format 


A nonzero value for a word is the address to which control passes when that 
particular trap occurs. A zero value for a word indicates that you have no interest 
in handling that exception. 


Octal Octal 
Offset Offset 
| [eit eaeens orononontmemarr ower] 0 
| manor pretstonvoaion | 2 
s | TotvapereweutontaseTinr | 
7 | season stan OT atucion | 8 


The contents of the program status register and the program counter (PS and PC) 
at the time of the exception have been pushed on the stack when the exception- 
handling routine is entered. Certain other values may have been pushed on 

the stack. The values depend on the exception. If the exception was a memory 
protect violation, the stack contains: 


(SP) —> Instruction backup register (SR1) 

3 Virtual PC of the faulting instruction (SR2) 
Memory protect status register (SRO) 
(PC) at time of exception 
(PS) at time of exception 


NOTE 


The RSX emulator returns zero for SRO and SRI: SR2 contains the PC 
at the time of the exception. 


If the exception was a TRAP instruction or EMT other than 377, the stack 
contains: 


(SP) —> Instruction operand (low-order byte) times 2, high-order bits cleared 
(PC) at time of exception 
(PS) at time of exception 


All items except the (PS) and (PC) must be popped from the stack before the 
exception-handling routine exits. You can then return control to the point where 
execution left off with an RTI or RTT instruction. 


Macro Expansion 


SVTKS SSTTBL, 4 

- BYTE 105.,3 ;DIC = 105., DPB LENGTH = 3 WORDS 
-» WORD SSTTBL ; ADDRESS OF SST TABLE 

- WORD 4 ;SET TABLE LENGTH = 4 WORDS 


Local Symbol Definitions 


S.VTTA Table address (2) 
S.VITL Table length (2) 


DSW Return Codes 


IS.SUC Successful completion. 
TE.SDP DIC or DPB size is invalid. 
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5.30 TFEAS$ — Test for Task Feature 


5-62 TFEA$ 


The TFEA$ directive tests for the presence of a task specific software option, 
such as fast-mapping turned on by the /FM switch in the TKB when the task was 
built. 


Macro Call 

TFEA$ sym 

where: 

sym is the symbol for the specified task feature. 
The supported task feature symbols are: 


Symbol Value Meaning 


T2$DST 15. AST recognition disabled (IS.SET=disabled) 
T4$DSP 34, Task was built /ID or has turned I&D on 
T4$FMP 40. Task has fast mapping turned on 


Macro Expansion 


TFEAS T4SFMP 
- BYTE LT hegee ;TFEAS MACRO DIC, DPB size = 2 words 
. WORD T4SFMP ;feature identifier 


Local Symbol Definitions 
F.TEAF Feature identifier 


DSW Return Codes 


IS.CLR Successful completion; feature not present (=0) 
IS.SET Successful completion; feature present (=2) 
TE.ADP Illegal DPB address 

TE.SDP Invalid DIC or feature identifier code 


NOTE 


The full list of RSX-11/M-PLUS feature identifiers is not supported on 
RSTS/E. 


5.31 UMAP$ — Unmap an Address Window 


The UMAP$ unmaps a specified address window from a resident library. The 
unmapping does not eliminate the window (created with a CRAW$ directive) or 
release the APRs used by the window. The virtual address window can now be 
remapped to new actual memory locations with the MAP$ directive. 


Privileges Required 


None 


Macro Call 
UMAP$ adr 
where: 


adr is the address of an 8-word area defining the window to be unmapped. The 
UMAP$ directive also returns information to this area. Two supplementary 
directives are available to define (WDBDF$) or define and fill (WDBBK$) such an 
area, called the window definition block, or WDB. 


Macro Expansion 


UMAPS WDBADR 
- BYTE L23..%-2 ;DIC=123., DPB SIZE=2 WORDS 
- WORD WDBADR 


Data Passed in WDB 


Mne- Octal Octal Mne- 
monic Offset Offset monic 
[mn _| 2 
s(n | 
{nin | 


adr+W.NID is the ID of the window to be unmapped (returned at the same location 
in the WDB by the CRAW$ directive). 
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5-64 UMAP$ 


Data Returned in WDB 


Mne— 
monic 


Octal Octal Mne- 
Offset Offset monic 
‘mm | 
smn | 
s[ mine | 
[inn 4 


adr+W.NSTS is the status flag. Bit 14 = 1 (WS.UNM) if the window specified was 


successfully unmapped. 


Local Symbol Definitions 


U.MABA Window definition block address (2) 


DSW Return Codes 


IS.SUC 
IE.ITS 


Successful completion. 


The window ID specified is either invalid (outside the range 1 to 7) or not 
currently mapped. 


5.32 WDBBK$ and WOBDF$—Define and Fill WDBs 


Two directives are available for use with Window Definition Blocks (WDBs): 
WDBDF$ and WDBBK$. 


The WDBDF$ directive assigns literal values to the offsets and status bit 
mnemonics shown for the WDB areas for the CRAW$, ELAW$, MAP$, and 
UMAP$ directives. You can use these mnemonics to reference offsets and bit 
values in a WDB you have allocated space for in your program. 


The WDBBK$ directive defines these offsets and, in addition, generates code to 
allocate space for the WDB and fills it with values you specify in the call. 


Privileges Required 
[Not applicable] 


Macro Cail 
WDBBK$ apr,siz,rid, off,len, <bit1 ![bit2!bit3]> 


where: 

apr is the base APR. 

siz is the size of the window. 

rid is the resident library ID. 

off is the offset into the library, in 32-word blocks. 

len is the length to be mapped. 

bit... are the mnemonic values for bit settings, separated by exclamation points. The 


following mnemonics are defined for CRAW$: 


WS.64B Means allow 32 word alignment, rather than requiring 256 word 
alignment. 


WS.MAP Indicates the window is to be mapped 
WS.RED # Means map with read-only access 
WS.SIS Means map in supervisor mode I-Space 
WS.UDS Means map in user mode D-Space 
WS.WRT Means map with read/write/access 


Macro Expansion 
WDBBKS 7,128.,0,0,0,<WS.MAP !WS.RED> 


.BYTE 0,7 
.WORD 0 
.WORD 128. 
.WORD 0 
.WORD 0 
.WORD 0 


- WORD WS .MAP!WS.RED 


When used in a CRAW$ directive, this WDB creates a window 4K words long (128 
by 32-word blocks) in APR 7. The call also specifies an offset and map length of 
zero and read-only mapping. Note that to use this WDB, you have to supply the 
resident library ID, which you get from the RDB returned by an ATRG$ call. To 
fill in the library ID, move the word at offset R.GID in the RDB to offset W.NRID 
in the WDB. 


The WDBBK$ directive also defines the offsets and bit settings that the ELAW$, 
MAP$, and UMAP$ descriptions refer to. 
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9.33 WSIG$ — Wait for Significant Event Flag 


5-66 WSIG$ 


The WSIG$ directive is included for compatibility with RSX-11M. In RSX-11M 
some recoverable error conditions require waiting for a significant event to 
happen, at which time a retry of the operation that failed may succeed. On a 
RSTS/E system, any events that may be termed significant within the RSTS/E 
monitor are transparent to user jobs. Hence, the WSIG$ directive in RSTS/E 
merely causes the calling job to sleep for one second. The job can then retry 
whatever operation failed previously. 


+] 


Privileges Required 
None 

Macro Call 

WSIG$ 


Macro Expansion 


WSIGS 
- BYTE 49.,1 ,DIC=49., DPB SIZE=1 WORD 


Local Symbol Definitions 


None 


DSW Return Codes 


IS.SUC Successful completion. 
IE.SDP DIC or DPB size is invalid. 


5.34 WTSES$ — Wait for Single Event Flag 


The WTSE$ directive is included for compatibility with RSX-11M, in which some 
programs are written with a QIO$ followed by a WISE$, to cause the program 
to wait until the I/O is complete. This has the same effect as a QLOW$ directive. 
Since all I/O is synchronous in RSX-emulation mode, QIO$ performs the same 
as QIOW$. Thus, the WTSE$ directive returns immediately; it performs no 
operation in RSTS/E. 


Privileges Required 
None 


Macro Call 
WTSE$ efn 
where: 


efn is the event flag number. (The RSX emulator ignores this parameter.) 


Macro Expansion 


WTSES 0 
- BYTE Ali ;DIC=41., DPB SIZE = 2 WORDS 
- WORD 0 ;FLAG IGNORED IN RSTS/E 


Local Symbol Definition 


W.TSEF Event flag number (2) 


DSW Return Codes 


IS.SUC Successful completion. 
TE.SDP DIC or DPB size is invalid. 
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Chapter 6 


RT-11 Run-Time System Environment 


The RT-11 run-time system emulates the single-job monitor of the RT-11 
operating system on RSTS/E systems. You can use many of the programmed 
requests available to MACRO programmers on RT-11 systems. In addition, 
the RT-11 run-time system provides some directives, suited to the RSTS/E 
environment, that are not available for the RT-11 operating system. 


The size limit for programs running under the RT-11 run-time system is 27K 
words, slightly less than the 28K words allowed by the RT-11 operating system. 
The run-time system itself takes a 4K-word high segment. It also uses 1K 
words in the user job image area as a scratch pad. As Chapter 2 notes, run-time 
systems are usually mapped read-only, so they can be shared by more than one 
user on a RSTS/E time-sharing system. However, the RT-11 operating system lets 
you access certain areas within the resident monitor. Thus, to allow a similar 
capability under RSTS/E, these areas must be located in the user job image area, 
which is mapped read/write. 


If you use the RT-11 directives (see Chapter 7), you must assemble your program 
with the MACRO assembler and link the modules with the LINK linker. The 
RSTS/E RT-11 Utilities Manual describes how to run MACRO and LINK to 
assemble and link your program. 


6.1 Advantage: Transportable Code 


The RT-11 directives are useful if you are coding a program to be run under both 
the RT-11 and RSTS/E operating systems. RSTS/E emulates the majority of the 
RT-11 single-job programmed requests. Of those which are not, most are ignored 
on RSTS/E systems, including the foreground/background (FB) and extended 
memory (XM) calls. That is, most RT-11 directives do not cause errors on RSTS/E 
systems (see Chapter 7 for a list of exceptions). 


Those RT-11 requests that are emulated are fitted to the RSTS/E environment. 
For example, under the RT-11 operating system, there are three types of read: 


e (READ —Initiates a read operation and transfers control back to the user 
program; the read may or may not be complete. 


e (READW—Initiates a read operation and transfers control back to the user 
program only after the read operation is completed. 


e READC—Initiates a read operation and transfers control to the user 


program; then, when the read is complete, transfers control to a user-specified 
completion routine. 
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Under RT-11 emulation, all I/O is synchronous; that is, control is returned 
to the user program only when the I/O is complete. So, .READ and .READW 
are implemented the same under RSTS/E as a "read and wait." The .READC 
transfers control to the completion routine when the read operation finishes. 


The significance of the differences depends on what you want to do. If you are 
transporting an existing program from RT-11 to RSTS/E, you can generally be 
confident that the program works as it should. 


If you are developing a program for RSTS/E only, you do not have to be concerned 
with how the directives work on RT-11. You can choose .READ or .READW: both 
work the same. You can also choose .READC if, for example, you wanted to code 
one completion routine to be used after different read operations. 


If you are developing a program on RSTS/E to be run under RT-11, or both 
RSTS/E and RT-11, you need to know how the directives work under RT-11 and 
under RSTS/E. You can choose between .READ, .READW, and .READC according 
to what they do on both systems. 


Chapters 6 and 7 describe what RT-11 directives are available, as well as what 
they do under RSTS/E. See the RT-11 Programmer’s Reference Manual for a 
complete description of how these directives work in the RT-11 operating system 
environment. 


You can also transport assembled (binary) programs from RT-11 systems to 
RSTS/E systems, if you keep in mind the limitations of the emulated RT-11 
run-time system environment. You must change the run-time system name that 
RSTS/E maintains in the file directory entry for each runnable file. The easiest 
way to do this is with the /RUNTIME_SYSTEM qualifier in COPY. For example: 


COPY MTO:*.* *,*/RUNTIME SYSTEM=RT-11 


This command transfers all files on magnetic tape unit 0 to your account on the 
public disk structure as files to be run under the RT-11 run-time system. 


For binary files that have already been transferred to your system, type: 


SET FILE file.typ/RUNTIME SYSTEM=RT-11 


de Ceo 6 Be ee ee 
6.2 General Services 


Besides transportable code, the RT-11 emulator provides: 


° Simple input/output. The I/O operations under the RT-11 run-time system 
are simple to code and include file-structured input/output operations. 


° Fast program development. The LINK linker executes faster than its RSX 
emulator counterpart TKB. However, LINK does not provide as many 
features. 
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6.3 System Macro Library 


The RT-11 emulator directives that you code inte your program are macros; 
MACRO-11 expands them into executable code at assembly time. The macro 
expansions for the RT-11 emulator directives are contained in the system macro 
library ($SYSMAC.SML). You can name this library file in the input-file list when 


you assemble your program. For example: 
MACRO OBJ, OBJ=$SYSMAC.SML/M, SRC1, SRC2 


(MACRO-11 searches the library automatically to resolve undefined symbols, so 
this is not really necessary.) 


However, you must use the MACRO-11 .MCALL directive in your code to define 
the directives you use as external macros needed to assemble the source program. 
The .MCALL must appear before the first directive is called. For example: 


.MCALL .READ, .DATE,.... 


- DATE 


Alternatively, you can enable automatic macro library search using the .ENABL 
MCL macro directive. See the PDP-11 MACRO-11 Language Reference Manual 
for details. 


Note that some RT-11 emulator directives have the same form as general monitor 
directives (.DATE, for example). If you want to use the RT-11 .DATEH, specify it in 
an .MCALL directive. Then, regardless of whether you assemble with the prefix 
file COMMON.MAC, the .DATE is expanded from the system library as a call to 


the RT-11 run-time system. 


If you want the general monitor .DATE, do not specify .DATE in an .MCALL 
directive. Instead, use the special prefix emulator trap (EMT) instruction (EMT 
377) immediately before the .DATE call, and assemble with COMMON.MAC. 


NOTE 


You must precede all general monitor directives that you use with an 
EMT 377. RT-11 uses EMTs in the range 0 to 100, the same range 
used by the RSTS/E general monitor directives. To bypass the general 
monitor calls, the RT-11 run-time system defines a special prefix EMT 
for the monitor (see Chapter 2), so all EMTs except those preceded by 
an EMT 377 are processed by the RT-11 run-time system. 


You should not use the general monitor calls .CHAIN, .EXIT, .CORE, 

.RTS, .FSS, .RUN, or .CCL from a program running under control of 

the RT-11 run-time system. Results from using these directives under 
RT-11 emulation are unpredictable. 
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6.4 Directive Processing 


It is easier to understand how you specify RT-11 directives and their arguments if 
you first understand how the directives are expanded at assembly time, and how 
they are processed by the RT-11 run-time system at execution time. 


Generally, the expansions end with an EMT instruction passing control to the 
RSTS/E monitor. The monitor then passes control to the RT-11 run-time system 
for processing. 


NOTE 


The RT-11 run-time system has the PF.EMT bit set in the PFLAG 
word in the pseudovector region (see Chapter 2). Thus, the RT-11 
run-time system can use all possible values in the low byte of the EMT 
instruction, just as the RT-11 operating system does. The low-byte of 
the PFLAG word is set to 377, which, in combination with the setting 
of the PFEMT bit, defines the special prefix EMT 377. 


The RT-11 run-time system examines the low byte of the EMT instruction to 
determine either the action to be performed or the place to look for information 
that defines the action to be performed. 


For example, if the call translates to code ending in an EMT in the range 340 to 
357, the RT-11 run-time system determines the action to be performed from the 
EMT and looks in general register RO and/or on the stack for other arguments 
used in the call. 


If, on the other hand, the call translates to an EMT 374 instruction, the RT-11 
run-time system looks in RO for a one-byte function code and, if necessary, a 
one-byte argument. For an EMT 375 instruction, the RT-11 run-time system 
looks in RO for the address of an argument block. It then examines the argument 
block to find the function code defining the action and whatever other arguments 
it expects, depending on the function. 


Table 6-1 summarizes the EMTs that the RT-11 run-time system processes. 
Unless you want to bypass the directive expansions and load RO and other 
arguments yourself, Table 6-1 is important to you because: 


e All the directives use general register RO. You must preserve the contents of 
RO, if necessary, by saving and restoring the contents before and after issuing 
a directive. Some directives return information to RO; otherwise, the contents 
of RO are unpredictable upon completion of a call. All other general registers 
are preserved as you left them. 


¢ Some of the directives require that you allocate space in your program for 
arguments. The expansions for such directives fill the argument block you 
specify in the call with the values you specify as other arguments in the call 
(see the next section "Call Forms"). 


If an error occurs when a directive is processed, control returns to the user 


program with the carry bit set in the PSW and an error code in byte 52 of the low 
512. bytes of memory. 
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Table 6-1: EMT Instructions Recognized by the RT-11 Run-Time System 


EMT Low-Byte 


Meaning 


EMT 377 


EMT 376 


EMT 375 


EMT 374 


EMTs 372-373 


EMTs 360-371 


EMTs 340-357 


EMTs 0-337 


Reserved; this is the special prefix EMT. You must code this EMT 
immediately before any of the general monitor calls in Chapter 3. 


Used internally by the RT-11 run-time system. Never execute this 
EMT from a user program; the program aborts with an error. The 
error message displayed is: 


2M -OVLY error at user PC nnnnnn." 


Indicates a call that has several arguments: RO contains the ad- 
dress of the first byte of an argument block. 


(RO) = | address of argument block | 


Indicates a call with one argument. RO contains a function code in 
the high-order byte and the argument in the low-order byte. 


Ignored by the RT-11 run-time system. Do not use these EMTs; they 
are reserved for future use by Digital. 


EMTs specific to the RT-11 run-time system under RSTS/E; not 
available under the RT-11 operating system. 


Indicates a directive that expects arguments either on the stack, in 
RO, or both. 


Indicates a directive used by Version 1.0 of the RT-11 operating 
system. These EMTs are also recognized by the RT-11 run-time 
system. 


6.5 Call Forms 


Chapter 7 shows RT-11 directive calls in two basic formats: those with an area 
argument and those without. The area argument indicates that the call uses an 
argument block. You must allocate space for the argument block. 


6.5.1 Format for Calls Using Argument Blocks 


The previous section describes how directives with an area argument use an 
argument block. Chapter 7 shows the format for these directives as: 


.RTCALL area, argl, arg2, ...., argn 
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The area argument is the address of the first byte of the area you have set aside 
for the argument block. The remaining arguments (argl, arg2, and so forth) are 
the values needed for the call. The RT-11 emulator places them in the argument 
block at execution time. 


In general, the argument block format is: 


aes 


RO points to location x. The high byte (location x+1) contains the function code 
defining the action to be performed. The low byte defines a channel number, if 
one is needed for the call. Remaining arguments, if any, are stored in subsequent 
words. | 


Consider the hypothetical directive .HYPOT, using four arguments including the 
area argument: 


-HYPOT area, argl, arg2, arg3 


If you were to specify all four arguments in the call, at assembly time MACRO-11 
expands the call to a code that: 


¢ Moves the area argument (an address) to RO. 


¢ Moves the function code for .HYPOT to the address specified by (RO)+1, 
and, if a channel number is used, moves that channel number to (RO). (The 
notation (x) means the contents of x — thus the channel number is moved to 
the address specified by the contents of RQ.) 


e Moves remaining arguments to subsequent words in the argument block. 


e Executes an EMT 375. 


Thus, all of the arguments for this form should be appropriate as operands in 
MOV instructions, For example: 


AREA: .WORD 0,0,0 


.HYPOT #AREA, #4,NUMNUM, #300 


Under certain conditions, you can leave out arguments in directives using an 
argument block. If you leave out area, for example, you must load RO with 
the address of the argument block yourself, before executing the directive. For 


example: 
MOV #AREA, RO 
.HYPOT , #4, NUMNUM, #300 


6-6 RT-11 Run-Time System Environment 


If you leave out any of the other arguments, the expansion does not load any new 
values into those positions in the argument block; those words are left untouched. 
For example: 


AREA: .WORD 0,0,0 


-HYPOT #AREA, ,NUMNUM, #300 


The execution of .HYPOT uses the value 0, the contents of location NUMNUM, 
and 300 as arguments. Suppose that the following directive is executed next: 


-HYPOT  #AREA, #3,, #200 


When the directive is executed, the argument block contains the value 3, the 
contents of location NUMNUM, and 200. 


6.5.2 Format for Calls Not Using Argument Blocks 


For those calls that do not use an argument block, Chapter 7 shows the format 
as: 


-RTCALL arg1, arg2, ..., argn 


These directives expand to code that stores the arguments, if any, in RO and/or 
the stack. (The RT-11 emulator removes any values pushed on the stack before 
control returns to the user program.) 


Again, the arguments should be appropriate as operands in MOV instructions. 
You can omit certain arguments for this form; Chapter 7 indicates these possible 
omissions with brackets when it describes the directive calls. For example, if the 
macro call format was as follows, you could leave out the last argument: 


HYPOT arg, arg2l, arg3] 


6.6 Channel Number and Device Block Arguments 


Many RT-11 directives use arguments that define a channel number and device 
block. A device block is a 4-word area containing the device and file specification. 
The following general comments apply to these arguments. 


6.6.1 Channel Number Arguments 


Like the general monitor calls, RT-11 directives which handle I/O use a channel 
number to refer to a device. Allowable RT-11 channel numbers range from 0 

to 15. When you open a file or device using the RT-11 directives LOOKUP or 
ENTER, you give a channel number in this range. The RT-11 emulator relates 
the number specified in the call to the first free RSTS/E channel number, with 
the following considerations: 


e The job’s terminal (RSTS/E channel 0) is never free for the emulator to relate 
to an RT-11 channel number. In RT-11, you do I/O to the job’s terminal with 
specific directives, such as PRINT and .GTLINE. Thus, since RSTS/E channel 
numbers range from 0 to 15 but RSTS/E channel 0 is always busy as far as 
the RT-11 run-time system is concerned, you can open up to 15 channels using 
any 15 of the 16 possible RT-11 channel numbers (ranging from 0 to 15). 
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e The RT-11 emulator always attempts to allocate RT-11 channel number 15 
to RSTS/E channel 15. Channel 15 is the channel on which the monitor 
opens the user job image file when RSTS/E executes a .RUN directive (see 
Chapter 3). The run-time system loads the file and begins its execution. If 
the program is overlaid, the run-time system keeps channel 15 open. If not, 
the run-time loads the file and then closes channel 15. 


Thus, if your program is not overlaid and you open RT-11 channel 15, the 
call succeeds (unless you already have channel 15 open). If your program is 
overlaid, you cannot open channel 15; any attempt to do so results in an error 
indicating the channel is in use. | 


Other than channel 15, there is no correspondence between the RT-11 channel 
number and the RSTS/E channel number. They may or may not be the same. 


6.6.2 Device Block Arguments 


Several RT-11 directives use a device and file specification. The argument in 
these cases is an address pointing to the first word of a 4-word device block 
that you allocate in your program. The format of the device block is 12 RAD50 
characters: 


device and unit number 
| filename | 
(2 words) 


file type 


You can use any valid RSTS/E device and unit number (0-7) for the first word of 
the device block. You can also define user logical names up to three characters 
long. If you need device numbers that have more than one digit (for example, 
KB27 or TT12), you must use the following steps to form the algorithm: 


~«— (devblk) 


1. Form the RAD50 representation of unit zero of the device you want. For 
example: 


BASEKB=*RKBO 


2. Add the decimal value of the unit number wanted. For example, to get the 
proper representation of KB36: 


KBN3 6=BASEKB+36. 


3. Use this value as the first word of the device block. For keyboards, there is 
no file name and type, so you can construct the device block as: 


DEVBLKE: .WORD KBN36 
. WORD 0,0,0 


NOTE 


If you assign a logical name with the same RADSO bit pattern as 
some device/unit-number that you construct, the logical name takes 
precedence. The previous example, for instance, forms the RAD50 bit 
pattern equal to the ASCII characters KCZ. Thus, if you assign the 
logical name KCZ to the line printer, any call referring to DEVBLK in 
the previous example would use the line printer not KB36. 
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6.7 Low 512. Bytes for RT-11 Run-Time System 


Table 6-2 summarizes the locations in the low 512. bytes of virtual address space 
that the RT-11 run-time system uses. 


Table 6-2: Locations in First 512. Bytes That RT-11 Uses 


Locations 


30,31 


32,33 


40,41 
42,43 


44,45 


46,47 


Contents 


Contains the contents of FIRQB+FQNENT at the time the .RUN was 
executed. (See the .RUN description in Chapter 3, and PRUN description 
in Chapter 2.) 


Contains the contents of XRB+0 when the run-time system was entered at 


P.RUN (see Chapter 2). 
Contains the starting address of the job. 


Contains the initial value of the stack pointer. If this value is not set 
by the user program in an .ASECT or through a LINK option, the LINK 
linker defaults this word to 1000. 


Contains the Job Status Word (JSW). RSTS/E uses JSW as a flag word for 
the run-time system. Certain bits are maintained by the RT-11 run-time 
system exclusively, while others can be set or cleared by the user program. 
The bits you can set are marked with an asterisk in the following list. 

Do not use currently unassigned bits for your own purposes; future RT-11 
run-time system releases may use them. 


Bit Meaning 

*15 Core common bit. If set with .ASECT, preserves core common 
when the user program is executed. 

*14 Lowercase bit. When set, disables automatic conversion of 
lowercase to uppercase. 

*13 Reenter bit. When set, indicates that you can restart the pro- 
gram from the terminal with the REENTER command. 

*12 Special mode TT bit. When set, indicates that the job is in a 


special keyboard input mode. See .TTYIN/.TTINR directive 
descriptions, Chapter 7. 


9 Overlay bit. When set, indicates that the job uses the LINK 
overlay structure. 
8 CHAIN bit. If set, virtual addresses 500-776 are loaded from 


the memory image file when the job is started. (These words are 
normally used to pass parameters between programs.) the RT-11 
run-time system sets the bit if you entered the job with the RT-11 
CHAIN directive. 

*6 Inhibit TT wait bit. When set, indicates that the job can accept 
input from the job’s terminal in ODT mode with .TTYIN/.TTINR; 
that is, one character at a time, as you type the characters rather 
than one character at a time after you type a whole line. 

Points to the first word of the RT-11 read/write scratch pad area in the 

user job image area. 


(continued on next page) 
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Table 6-2 (Cont.): Locations in First 512. Bytes That RT11 Uses 


Locations Contents 


50,51 Contains the high memory address. The run-time system maintains the 
highest virtual address the user program can use in this word. It is 
initially set to the address of the last word of the user program. You can 
change it with the SSETTOP directive (see Chapter 7) to any address up to 
the start of the scratch pad area. That is, the maximum value this word 
can be is the contents of the word at location 46,47 minus 2. 


52 Contains the EMT error code. If the directive results in an error, the code 
number of the error is always returned in byte 52 and the carry bit is set. 
Always refer to location 52 as a byte, not a word. 


54,55 Contains the beginning address of the scratch pad area. 


6.8 Scratch Pad Area in User Job Image 


The RT-11 run-time system uses part of the user job image space as a scratch 
pad. Some of the information in this scratch pad is the same as the information 
in the RT-11 operating system, as the RT-11 Programmer’s Reference Manual 
describes. Other information is unique to RSTS/E. For example, you can set a 
word in this area with a PPN to be used when opening a file. RT-11 does not 
allow a PPN in its file specification; RSTS/E does. 


In any case, the RT-11 emulator adds the scratch pad area to the end (high 
virtual addresses) of the user job image at execution time. If you do not use 
RT-11 SIZE command (see the RSTS/E System User’s Guide), the emulator 
determines the highest address of the program from the .SAV file, an item which 
the LINK linker calculates, and rounds the address up to the next multiple of 
1024 (1K words) to determine the starting address of the scratch pad. If you use 
the RT-11 SIZE command, the emulator places the scratch pad in the top 1K 
words of the address space that SIZE requests. 


Thus, the maximum size of MACRO programs running under the RT-11 run-time 
system is 27K words. Any program larger than this causes the ??7Maximum 
memory exceeded error message when the file is run. 


You can determine the start of the scratch pad area from word 54 in the low 512. 
bytes of memory. 
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Table 6-3 lists the offsets to locations in the scratch pad area that may be of use 
to you. 


Table 6-3: Offsets to Important Scratch Pad Area Locations 


Octal Mnemonic 
Offset Offset Contents 


0 PPN If nonzero, used as a PPN for all of the calls named in this 
section except .READ and .WRITE. (Note that for SETFQB, 
this value is loaded into FIRQB+FQPPN and overrides any PPN 
resulting from examination of the string by the corresponding 
.CSISPC directive.) 


For .READ and .WRITE, this word forms the modifier word (at 
XRB+XRMOD) in the corresponding RSTS/E .READ or .WRITE 


directive. 


2 PROTEC If nonzero, this word is the protection code to be used for all of 
the calls named in this section except .READ and .WRITE. (Note 
that for SETFQB, this value is loaded into FIRQB+FQPROT and 
overrides any protection code resulting from examination of the 
string by the corresponding .CSISPC directive.) 


For .READ and .WRITE, this word forms the most significant 
bits of the block number in the corresponding RSTS/E .READ or 
WRITE (at XRB+XRBLKM). This value supplements the block 
number argument from the RT-11 .READ or .WRITE call. 


4. MODE For RT-11 calls LOOKUP, .ENTER, and .REOPEN, this word 
forms the mode word at FIRQB+FQMODE in the corresponding 
RSTS/E CALFIP call. For .SETFQB, this word is loaded into 
FIRQB+FQMODE and overrides any /MODE qualifier that the 
.CSISPC directive finds. 


6 CLUSTR For RT-11 directives that create files, such as .ENTER, this word 
forms the cluster size (at FIRQB+FQCLUS) for the corresponding 
RSTS/E CALFIP call. For .SETFQB, this word is loaded into 
FIRQB+FQCLUS, and overrides any /CLUSTERSIZE qualifier 
that the .CSISPC directive finds. 


10 POSITN For RT-11 directives that create files, such as .KNTER, this 
word forms the device cluster number for file placement (at 
FIRQB+FQNENT) in the corresponding RSTS/E CALFIP call. 
For .SETFQB, this word is loaded into FIRQB+FQNENT and 
overrides any /POSITION qualifier that the .CSISPC directive 
finds. 


12 CRMSBS For RT-11 calls that preallocate space for a file on its creation 
(ENTER), this word forms the most significant bits (MSBs) of 
the file size (at FIRQB+FQSIZM) in the corresponding CALFIP 
call. For .SETFQB, this byte is loaded into FIRQB+FQSIZM. 


(continued on next page) 
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Table 6-3 (Cont.): Offsets to Important Scratch Pad Area Locations 


Octal Mnemonic 
Offset Offset Contents 


66 NOCTLC This word is used by the RT-11 run-time system to stop user- 
entered Ctrl/Cs from interrupting program execution during 
certain crucial sequences (.SRESET, .HRESET, .LOOKUP, 
-ENTER, .REOPEN, .CLOSE, and .SAVESTATUS). 


When set to 177777, user-entered Ctrl/Cs interrupt execution. 
A zero or positive value inhibits Ctrl/C interrupts. While this 
word is zero or positive, any user-entered Ctrl/C increments the 
contents of this word by one. 


When the emulator reenables Ctrl/Cs, it processes any pending 
Ctrl/C by either: 


e Passing control to a user routine specified with .SETCC 
(Chapter 7) 

e Ifno SETCC is in effect, passing control to the job keyboard 
monitor. If the job keyboard monitor is RT-11, the keyboard 
monitor commands CONTINUE or CCONTINUE resume 
execution of the program at the point where the interrupt 
occurred. Your program can clear this word to inhibit 
Ctrl/Cs, process them later in whatever manner you see 
fit, and reenable Ctrl/C interrupts by setting this word 
to 177777. However, note that the RT-11 emulator clears 
the word and then reenables interrupts when .SRESET, 
-HRESET, .LOOKUP, .ENTER, .REOPEN, .CLOSE, or 
SAVESTATUS is executed. 


276 Kmulator version number. The same as the RT-11 operating 
system version number that the current RT-11 run-time system 
emulates. 


277 Kmulator release number. The same as the RT-11 operating 
system release number that the current RT-11 run-time system 
emulates. 


300 Configuration word. Set for RSTS/E environment, as follows: 


If FP11 floating-point hardware exists, bit 6 is set to one. Bit 
9 is always set to one, and all other bits are set to zero. 

(If your program tests these bits on an RT-11 system, the 
code also works on RSTS/E.) 


370 Extension configuration word. Under RSTS/E, bits 0-3 are 
always zero, bit 8 is always one (indicating the EIS option is 
present), and bits 9, 14, and 15 are always zero. (The conditions 
they indicate on RT-11 systems are not determinable by the 
RT-11 run-time system under RSTS/E.) 


372 SYSGEN options word. This word is always zero on RSTS/E 
systems. 

374 User job image size. This word is always zero on RSTS/E 
systems. 
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The first six words in the scratch pad are of special significance; the following 
general comments apply: 


The directives .LOOKUP, .ENTER, .RENAME, .REOPEN, .DELETH, and 
SETFQB examine the first six words, use any values there as described, and 
clear the first six words before returning control to the user program. 


The directives .READ and .WRITE examine, use, and clear only the first two 
words. 


The .CSIGEN directive clears the first six words before performing any of the 
LOOKUP and .ENTER calls resulting from its examination of the command 
string. 
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Chapter 7 


RT-11 Emulator Directives 


RSTS/E does not emulate some of the RT-11 operating system’s single-job monitor 
calls. RSTS/E ignores the following: .CMKT, .HERR, .LOCK, .QSET, .MRKT, 
-RELEASE, .SERR, and .UNLOCK. The .CDFN call always returns an error 0 
on RSTS/E systems. The following single-job monitor calls are not expanded to 
include EMTs, and their results on RSTS/E systems are unpredictable: .IINTEN, 
.MFPS, .MTPS, and .SYNCH. 


The RT-11 foreground/background (FB) and extended monitor (XM) calls are not 
supported; they are essentially ignored on RSTS/E systems. They do not return 
errors. 

Table 7—1 lists the directives that are not processed by the RT-11 run-time system 
on RSTS/E systems. 


Table 7-1: RT-11 Calls Not Functional on RSTS/E 


Return 
Ignored Error 0 Unpredictable 
.CMKT | .CDFN ANTEN 
.HERR .MFPS 
“LOCK .MTPS 
.QSET SYNCH 
.MRKT 
.RELEASE 
SERR 
UNLOCK 
All FB calls 
All XM calls 


Table 7—2 lists the directives that are processed by the RT-11 run-time system on 
RSTS/E systems. 
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Table 7-2: RT-11 Run-Time System Directives 


Mnemonic 


es 
V2... 


WRITE 
.WRITW 
.WRITC 


-READ 
-READW 
-READC 


-REOPEN 


SAVESTATUS 


-RENAME 
ENTER 
.LOOKUP 


.DELETE 
CLOSE 


-PURGE 


-HRESET 
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EMT 


375 


375 


375 


375 


375 
375 
375 


375 
374 


374 


357 


Function 


Code 


Description 


Lets you assemble directives as they would 
be expanded under Version 1 or Version 2 of 
RT-11. 


Input/Output and File Operations 


11 


10 


Transfers data from a memory buffer to a file 
or device on an open channel. As with the 
-READ/W/C directives, .WRITE and .WRITEW 
operate identically on RSTS/E; .WRITC trans- 
fers control to a completion routine after the 
transfer is complete. 


Transfers data from a file or device on an open 
channel to a memory buffer. I/O is synchronous 
under RT-11 emulation on RSTS/E systems, so 
for all three reads, control returns to the user 
program only when the transfer is complete. 
.READ and .READW are identical on RSTS/E 
systems. .READC transfers control to a user- 
specified completion routine when the transfer 
is complete. 


Opens a file closed with SAVESTATUS. Using 
the .SSAVESTATUS/.REOPEN combination is 
easier than using standard opens and closes; 
the device, file name and type, and project- 
programmer number are saved automatically 
with .SAVESTATUS. You only need to keep 
track of the address in which you stored the 
file information to reopen it. 


Closes a file, keeping the information needed to 
-REOPEN the file later. 


Changes a file’s name on disk or DECtape. 
Creates a file and opens it on a channel. 


Opens an already existing file on a chan- 
nel. .LOOKUP can also be used for non-file- 
structured I/O operations. 


Deletes a disk or DECtape file. 


Terminates I/O operations on a channel, 
performing clean-up operations (positioning 
tape, and so forth) and releasing the channel 
for other use. 


Releases a channel without performing the 
normal clean-up operations. In particular, a 
file opened with .ENTER and not yet closed is 
not made a permanent file. 


Closes all open channels, without performing 
normal clean-up operations. In particular, files 
opened with .ENTER and not yet closed are not 
made permanent. 
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Table 7-2 (Cont.): 


Mnemonic 


SSRESET 
PRINT 
.GTLIN 


-TTYOUT 
-TTOUTR 


sTTYIN 
.TTINR 


.SPFUN 
SCCA 


.WAIT 


.CLRXRB 
(RSTS/E only) 


.CLRFQB 
(RSTS/E only) 


.DOFSS 
(RSTS/E only) 


-ERRPRT 
(RSTS/E only) 


SETCC 
(RSTS/E only) 


SETFQB 
(RSTS/E only) 


.RCTRLO 


.CSISPC 


.CSIGEN 


FETCH 


EMT 


352 
351 
345 
341 


340 


375 


374 


374 
371 


370 


365 


364 


362 


360 


355 


345 


344 


343 


Function 


Code 


RT-11 Run-Time System Directives 


Description 


Input/Output and File Operations 


Functions the same as .HRESET on RSTS/E. 
Displays an ASCII string on the job’s terminal. 
Accepts a line of input from the job’s terminal. 


Transfers one character from RO to the job’s 
terminal. 


Transfers one character from the job’s terminal 
to RO. 


Special Functions Related to I/O 


32 


35 


Performs special functions for disk, terminal, 
magnetic tape, and flexible diskette. 


Causes a Ctrl/Z entered by the user to be 
passed on to the user program. 


Checks to see if channel is open. 
Clears the XRB (see Chapter 2). 


Clears the FIRQB (see Chapter 2). 


Analyzes an ASCII string in memory for a 
RSTS/E file name and returns information 
as for .FSS (general monitor directive). Use 
instead of.FSS for programs running under 
RT-11 run-time system. 


Prints text corresponding to RSTS/E error code 
on the job’s terminal. 


Defines an entry point for Ctrl/C traps; allows 
the user program to handle its own Ctrl/Cs. 


Sets the FIRQB (see Chapter 2) from informa- 
tion returned by the .CSISPC directive. 


Restarts programmed output to job’s terminal 
that was stopped by user-entered Ctrl/C or 
Ctrl/O. 


Analyzes an ASCII string (in memory or 
from the job’s terminal) for a standard RT-11 
command, and sets up device blocks for later 
opens. 


Analyzes an ASCII string (in memory or 
from the job’s terminal) for a standard RT-11 
command, and opens files accordingly. 


Checks to see if device is available on the 
system. 


(continued on next page) 
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Table 7-2 (Cont.): RT-11 Run-Time System Directives 


Function 
Mnemonic EMT Code Description 


Special Functions Related to I/O 


.DSTATUS 342 _ Returns information about a device to an area 
in the user program. 


System/Job Information 


.GVAL 375 34 Returns the contents of a word in the scratch 
pad area. 

.GTIM 375 21 Returns the time of day. 

-.GTJB 375 20 Returns the current job number. 

.DATE 374 12 Returns the current date. 

.DATTIM 361 _ Converts date or time from RSTS/E internal 

(RSTS/E only) format to ASCII string. 

SETTOP 354 — Sets location 40 (indicating top of user job 


image area) to the address specified. 


Execution Control 


SFPA 375 30 Sets address to be entered for floating point 
errors. 

-TWAIT 375 4 Timed wait. Suspends job execution for speci- 
fied number of clock ticks. 

.TRPSET 375 3 Sets address to be entered for reserved instruc- 


tion and odd address errors; normally trapped 
to kernel mode addresses 4 and 10. 


-CHAIN 374 10 Transfers control to another program (file) to 
be run under the RT-11 run-time system. 

-DOCCL 367 — Hxamines a string for valid RSTS/E CCL 

(RSTS/E only) command. If valid, transfers control to new 


program. Use instead of .CCL (general monitor 
directive) for programs running under RT-11 
run-time system. 


-.GETCOR 366 _ Expands size of user job image. Use when 

(RSTS/E only) -CHAIN is used to transfer control to a pro- 
gram larger than the current program. In 
addition, use instead of .CORE (general mon- 
itor directive) for programs running under 
RT-11 run-time system. 


-DORUN 363 — Transfers control to another program (file) that 

(RSTS/E only) runs under a non-RT-11 run-time system. Use 
instead of .RUN (general monitor directive) 
for programs running under RT-11 run-time 
system. 


(continued on next page) 
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Table 7-2 (Cont.): RT-11 Run-Time System Directives 


Function 
Mnemonic EMT Code Description 


Execution Control 


EXIT 350 — Terminates execution of the calling job. Note 
that you should not use the RSTS/E .RTS or 
-EXIT directives from a program running under 
the RT-11 run-time system. 


The remaining sections of this chapter describe the directives in detail, in 
alphabetical order. Note that for all calls, you need only specify the first 
six characters. For example, the abbreviation SAVES works as well as 
SAVESTATUS. 


All the examples in this chapter show Version 2 expansions. Note that Version 
1 expansions require different arguments in the calls. See RT-11 system 
documentation if you need to use Version 1 expansions. 


RT-11 Emulator Directives 7-5 


7.1 .CHAIN — Pass Control to Another Program Under RT-11 


7-6 .CHAIN 


The .CHAIN directive transfers control to another program without altering 
the run-time system. The .CHAIN leaves I/O channels from the old program 
still open for the new program. Thus, you can get around the 27K word limit 
for programs to be run under the RT-11 run-time system. If the program you 
are chaining to takes more space than the current program, use the .GETCOR 
directive to expand the space allocated for the user job image area before 
executing the .CHAIN. 


Virtual addresses 500-507 are expected to contain the device and file name of 
the program to chain to, in the RT-11 device block format (see Chapter 6). The 
area from locations 510-777 can be used to pass information between the chained 
programs. Make sure, though, that the program you are chaining to does not 
inadvertently destroy the data in locations 510-777 by pushing data on the stack. 
Note that the linker defaults the initial stack setting to 1000. 


An executing program can tell whether it was chained to or run by some other 
means by examining bit 8 of the Job Status Word (JSW) (see Chapter 6). If bit 8 
= 1, the program was invoked with .CHAIN, and locations 500-777 are preserved 
from the program that issued the .CHAIN. If bit 8 = 0, the program was not 
entered with an RT-11 .CHAIN. 


The .CHAIN directive works only for RT-11-to-RT-11 transfers. If you want to 
chain to a program to be run under some run-time system other than RT-11, 

use the .DORUN directive (see Chapter 6). (The description of .DORUN also 

describes what happens for RT-11 programs receiving control from non-RT-11 

programs.) 

Privileges Required 


Read or execute access to the file. 


Macro Call 
.CHAIN 


Request Format 


Errors 


Since .CHAIN is intended to pass control to another program, no errors are 
returned to the calling program. If the new program cannot be chained to, the 
.CHAIN is abandoned, and the keyboard monitor is entered. (Control passes 
to the PNEW entry point of the RT-11 run-time system, which is the keyboard 
monitor’s entry point for RT-11.) 


Example 


The following code requests an expansion to 20K words and chains to a sample 
file named MYFILE.SAV in the user’s account: 


FILE: »RAD50 /MYF ILESAV/ ;Define text passed in chain 
MOV #20.,RO0 ;Indicate 20.K now needed 
» GETCOR 
CLR 500 ;Default for the device 
MOV #F ILE, 502 ;Move 
MOV #F TLE+2, 504 ; the 
MOV #F ILE+4, 506 : file name 
. CHAIN ;Invoke the new program 


-CHAIN 


7-7 


7.2 .CLOSE — Close a Channel 


7-8 .CLOSE 


Use the .CLOSE directive to terminate I/O on a particular channel. The .CLOSE 
directive: 


e Performs whatever action is appropriate to the device (such as updating a 


disk directory to indicate a new file, repositioning a magnetic tape, and so 
forth) 


e Frees the RT-11 channel number for use with another device 
e Frees the RSTS/E channel from its association with the RT-11 channel 


number (effectively making another channel available). 


A .CLOSE on a file opened with ENTER makes the file permanent; the file is 
tentative until that time. Note that, unlike the RT-11 operating system, RSTS/E 
does not deallocate unused space. Thus, if you preallocated space when you 
opened the file with ENTER, the file contains all this space after the .CLOSE. 


Privileges Required 


None 

Macro Call 

.CLOSE chanum 

where: 

chanum is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on 
channel numbers. 

RO Format 

Errors 


No errors are possible with the .CLOSE directive. RSTS/E ignores a .CLOSE for 
a channel that is not currently open. 


Example 


The following statement closes channel 5: 


-CLOSE #5 


7.3 .CLRFQB — Clear the FIRQB 


This directive clears the FIRQB area in the low 512. bytes of virtual memory (see 
Chapter 2). No data is passed or returned for this directive. 


Privileges Required 
None 

Macro Call 
.CLRFQB 


Note that .CLRFQB, like all RSTS/E-specific directives under RT-11, is not 
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 
No errors are possible with the .CLRFQB directive. 


Example 


The following example clears the FIRQB area in the low 512. bytes of virtual 
memory: 


~CLRFQB = EMT+370 


- CLRFQB 


-CLRFQB 7-9 


7.4 .CLRXRB — Clear the XRB 


7-10 CLRXRB 


This directive clears the XRB area in the low 512. bytes of virtual memory (see 
Chapter 2). No data is passed or returned with .CLRXRB. 


Privileges Required 


None 


Macro Call 
.CLRXRB 


Note that .CLRXRB, like all RSTS/E-specific directives under RT-11, is not 
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 
No errors are possible with the .CLRXRB directive. 


Example 


The following example clears the XRB area in the low 512. bytes of virtual 
memory: 


~-CLRXRB = EMT+371 


» CLRXRB 


7.5 .CSIGEN — Examine String for RT Command, Open Files 


The .CSIGEN directive examines a string (either in memory or from the job’s 
keyboard) to process a standard RT-11 command string. If the string is to be 
accepted from the job’s keyboard, the .CSIGEN first prints an asterisk (*) prompt 
on the keyboard and then waits for you to type a line. 


If the string is in the correct form, any files or devices open on RT-11 channels 
0 - 10 (octal) are closed and then either reopened or left inactive, depending on 
whether or not a file is given for that slot. For example: 


objfile,listfile, crefile=srcfilel,srcfile2,...srcfile6é 


channel 0 ch 2 3 4 10 


Any valid RSTS/E file specification can appear in the string, including file 
specifications with PPNs, and logical names. However, the file specifications 
cannot contain wildcards. Files on the left side of the equal sign are opened 
with .ENTER, and the files on the right side of the equal sign are opened with 
LOOKUP If the equal sign is missing, RSTS/E assumes an equal sign at the 
beginning of the string. For example, consider the string: 


NOW.OBJ,NOW.LST,NOW.CRE=THEN .MAC 


The file NOW.OBJ would be opened with .ENTER on channel 0; NOW.LST, on 
channel 1; NOW.CRF, on channel 2. The file THEN.MAC would be opened with 
-LOOKUP on channel 3. Two more examples are: 


NOW.OBJ, , NOW. CRF= 


The file NOW.OBJ would be opened with .ENTER on channel 0 and NOW.CRF on 
channel 2. Channels 1 and 3-10 would be inactive. 


LP: 
The line printer would be opened with .LOOKUP on channel 3. 


RSTS/E Options 


The file specifications can include any of the standard RSTS/E qualifiers pro- 
cessed by the monitor itself (see the .FSS directive, Chapter 3). These include: 
/CLUSTERSIZE, /RONLY, /MODE, /PROTECTION, /FILESIZE or /SIZE, and 
/POSITION. The RT-11 Emulator can handle any of these optional qualifiers that 
.CSIGEN finds in the command string. 


RT-11 Options 


The .CSIGEN directive under RSTS/E also does RT-11-type analysis of options. 
One or more options can appear after any of the file specifications. The general 
form of an option is: 


The slash (/) indicates an option; it must be followed by a one-character option 
code. (The character does not have to be printable.) The slash-character pair can 
be followed by one or more values. A colon (:) indicates that a value follows. If 
given, the colon must be followed by: 


e An octal number in the range 0 to 177777. 
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7-12 CSIGEN 


° A decimal integer in the range -32768. to 32767. (the terminating period 
must appear). 


° From one to three alphanumeric characters, with the first character alpha- 
betic. 


The .CSIGEN directive examines any options in the string to ensure that they are 
in the correct form, reformats them, and pushes them on the stack for the user 
program to examine. The information pushed on the stack is ordered by channel: 
if an option is given for the file specification for channel 0 (assuming there is 

a file specification in the first slot), it is pushed on the stack first, followed by 
option information for the file specification for channel 1 (if any), and so forth. 
The last word pushed on the stack is an integer value indicating the total number 
of options in the string. An option having two values is formatted as two options. 
The format is: 


: number of options in string ! 
value-flag/channel | option code (ASCII) | 


value (integer or RADS50) or next option 


Bit 15 of a value-flag/channel byte is set to one if the option had an associated 
value, to zero if it did not. Thus, if bit 15 is set, the next word is the value 
associated with the option. (The option code itself is in the low byte of this 
word.) If bit 15 is zero, the next word is the next option (if any). Bits 8 to 14 of 
a value-flag/channel byte indicate the RT-11 channel number with which the file 
specification having the option is associated. 


Privileges Required 


Read or write access to the files specified. DEVICE privilege is required to access 
a restricted device. 


Macro Call 

-CSIGEN devspc,defext,[cstrng]Llinbuf] 

where: 

devspc is ignored on RSTS/E systems. 

defext is the address of a four-word area containing default file types, in RAD50 


format. The format of the area is: 


default for files open on channels 3-10 


| default for file open on channel 0 


default for file open on channel 1 


default for file open on channel 2 | 


These values are then used when no corresponding file type is given in the 
examined string. For example, in the MACRO assembler, the first word 
would contain MAC in RAD50 format; the second, OBJ; the third, LST; and 
the fourth, CRE. 


estrng is the address of the ASCIZ string to be examined or a #0 if input is to 
come from the job’s terminal. If this argument is not specified, input is 
automatically taken from the job’s terminal. 

linbuf is the address where the original string (if accepted from the job’s ter- 
minal) is to be stored. This area should be 81. bytes long. The string 


will be terminated with a zero byte, instead of a carriage-return/line-feed 
combination. 


If this argument is omitted, the original string is not kept. 


Errors 


If an error occurs when input is accepted from the job’s terminal, the user gets 
another try. An error message is printed on the terminal, along with another * 
prompt, and the directive waits for you to type another line. 


If the string being examined is in memory and an error occurs, the carry bit is 
set, and one of the following error codes is returned in byte 52. The options and 
option-count are removed from the stack. 


Code Meaning 


0 Illegal command (bad separators, illegal file name, command too long, and so 
forth). 

af A device specification was not recognizable or the device is not available on the 
system. 

2 Unused. 

3 An attempt to open a file with .ENTER failed because of a full directory. 


An input file (to the right of the equal sign) was not found in a LOOKUP. 


Example 


The following example includes option switches and shows more clearly how 
options and values are pushed on the stack: 


DEFEXT: -RAD50 /MACOP 1LOP20P3/ 


.CSIGEN #0, #DEFEXT, #0 
Assume that the line typed at the job’s terminal is: 
OUTFIL/M:32., ,ODDFIL=[2, 200] HISFIL, DTO: HERFIL/G:NRD:20 


When control returns to the user program following the .CSIGEN, the file 
OUTFIL.OPI on the public structure has been opened with the .ENTER directive 
on channel 0, and the file ODDFIL.OP3 on channel 3. The file HISFIL.MAC on 
the public structure, under account [2,200], has been opened with the .LOOKUP 
directive. (If the calling job did not have the necessary privilege, an error mes- 
sage would have been displayed on the terminal, and another line accepted.) The 
file HERFIL.MAC on DECtape unit 0 has also been opened with .LOOKUP. 
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7-14 CSIGEN 


The stack contains: 


Octal 


Value 


000003 


102107 


000020 


102107 


055124 


100115 


000040 


Explanation 


Three options were found in the string. 
(The G option has two values.) 


Last option has a value, and the option is 
associated with channel 4. The option code 
is G. 

The value of the option is 20 (octal). 
Next-to-last option has a value, and the 
option is associated with channel 4. The 
option code is G. 

Value of option is NRD in RAD50 format. 
The first option has a value, and the 
option is associated with channel 0. 

The option code is M. 


The value of the option is 40 (octal). 


7.6 .CSISPC — Examine String for RT Command, Create Devblk 


Like .CSIGEN, the .CSISPC directive parses a string (either in memory or from 
the job’s terminal) to see if it is a valid RT-11-type command string. If the string 
is to be accepted from the job’s terminal, .CSISPC first displays an * prompt on 
the screen and then waits for you to type a line. Instead of closing and opening 
files, however, .CSISPC simply returns a 39-word block of information about 
the files named in the string. The user program can later use this information 
to open the files. See the previous discussion of .CSIGEN for command string 
format and option processing. 


Note that .CSISPC, like .CSIGEN, stores RSTS/E-specific file information 

(PPN, and so on) within the scratch pad area. Furthermore, you can issue a 
SAVESTATUS or .SETFQB referencing the device-block information returned by 
.CSISPC (although .SAVESTATUS works only for input files to the right of the 
equal sign when opened with .LOOKUP). 


If you use .CSISPC in this way, be sure that you reference addresses in the 
outspec area returned by .CSISPC. If you move the information in the outspec 
area and then refer to the new area in SAVESTATUS or SETFQB, the RSTS/E- 
specific information, such as PPN, is not used. (The emulator keeps a pointer in 
the impure area relating the PPN and other RSTS/E-specific information to the 
area returned by .CSISPC.) 


Privileges Required 


None 
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Macro Call 


.CSISPC outspc,defext,csirng[,linbuf] 


where: 


outspc 


defext 


is the address of a 39-word area to contain the file descriptors produced by 
-CSISPC. This area can overlay the space allocated to cstrng, if desired. The 
format of the information returned is: 


devbik for devblk for 


channel 0 channel 4 


devblk for 


devblk for 


channel 5 


channel 1 


devblk for 


channel 6 


devblk for 


channel 2 
devblk for 


channel 7 


devblk for 


channel 3 devblk for 


channel 10 


Information for the files for channels 0, 1, and 2 is stored in 5-word blocks. 
The first four words are RAD50 information in the standard RT-11 device 
block format (see Chapter 6). The last word is the file size indicated by 

a /FILESIZE or /SIZE option, if any was encountered for these files in the 
string. Since files on the left side of the equal sign are opened with .ENTER, 
they can have a size for preallocation. Information for the files for channels 
3 to 10 is stored in 4-word blocks, in the standard RT-11 device block format. 
If any files are omitted in the string, the corresponding 4- or 5-word block is 
filled with zeros. 


is the address of a four-word block containing the RAD5O default file types. 
(See the discussion of .CSIGEN for the format of this area.) These defaults 
are returned to the outspec area if no types are given in the examined string. 


estrng is the address of. the ASCIZ string to be examined or a #0 if input is to 
come from the job’s terminal. If this argument is not specified, input is 
automatically taken for the job’s terminal. The string must follow the rules 
for an RT-11 command string, as described for .CSIGEN. 

linbuf is the address where the original string (if accepted from the job’s terminal) 
is to be stored. This area should be at least 81 bytes long. The string is ter- 


minated with a zero byte instead of a carriage-return/line-feed combination. 
If this argument is omitted, the original string is not kept. 


Errors 


If an error occurs when input is accepted from the job’s terminal, the user gets 
another try. An error message is printed on the terminal, along with another * 
prompt, and the directive waits for you to type another line. 


If the string being examined is in memory and an error occurs, the carry bit is 
set, and one of the following error codes is returned in byte 52. The options and 
option-count are pushed from the stack. 


Code Meaning 


0 Illegal command line (bad separators, illegal file name, command too long, and so 
forth). 

1 A device specification was not recognizable or is not available on the system. 

Example 


The following code accepts a line of input from the terminal, checks it for RT-11 
command format, and stores the resulting device block information in a 39-word 
area called OUTSPC: 


DEFEXT: . WORD 0,0,0,0 ;No default file types 
OUTSPC: - BLKW 39. ;Device block area 


-CSISPC #OUTSPC, #DEFEXT, #0 
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7. .DATE — Return Current Date to RO 


7-18 .DATE 


The .DATE directive returns the current month, day, and year to RO in the 
following format: 


bit ,13 10, 9 5) 4 0 
month(1-12)} day (1-31) | year—72(0-31) | 


The year value in bits 4-0 is the current year minus 72. 


Note that this directive gets its date information from the RSTS/E clock. Unlike 
the RT-11 operating system, you do not set the values returned with the DATE 
keyboard monitor command. 


Privileges Required 
None 


Macro Call 
DATE 


RO Format 


Errors 
No errors are returned with the .DATE directive. 
Example 


The following subroutine can be assembled separately and linked to a user 
program: 


- LITLE DATE .MAC 

ceaieNe SEQUENCE: 

; JSR PC, DATE 
une NONE 


;OUTPUT: RO 


= DAY (1-31) 

, R1 = MONTH (1-12) 
: R2 = YEAR - 72 
-MCALL -DATE 


DATE: : - DATE ;Get the system date 


MOV RO,R2 ;Copy the date 

BIC #4C37,R2 | 

ASR RO 7Put month on a byte boundary 
ASR RO “os 

MOV RO, R1 ;Copy the date 

SWAB Rl ;Put month in the low byte 
BIC #*°C37,R1 :Isolate the month 

ASR RO ;Shift day to a byte boundary 
ASR RO = 

ASR RO ; 

BIC #°C37,RO ;Isolate the day 

CLC sIndicate no error 

RTS PC 

-» END 
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7.8 .DATTIM — Return Date or Time 


7-20 .DATTIM 


The .DATTIM directive is available only to RT-11 emulator users under RSTS/E; 
it is not available under the RT-11 operating system. .DATTIM converts a date 
or time from the RSTS/E system internal format (as returned by the .DATE 
directive, see Chapter 3) to an ASCII string suitable for printing. The format of 
the string is the same as that returned by the BASIC-PLUS DATE$ and TIME$ 
functions. That is, a date is in the form "27-Jun-84"; or, if the system uses the 
numeric date option, in the form "84.06.27". Similarly, a time is in the form 
"02:30 PM" or "14:30". 


The .DATTIM directive assumes that RO contains the address of the area to 
which the string is to be returned. It also expects to find the date or time in 
RSTS/E system internal format in the XRB. If a date is desired, it should be 

in XRB+0. If a time is desired, the word at XRB+0 should be cleared and the 
time stored in XRB+2. Note that these are the locations returned by the RSTS/E 
.DATE directive. 


You can request a specific format for date or time rather than accepting the 
format selected at system generation. If you set bit 15 of XRB+0 (date) or XRB+2 
(time), you request a specific format rather than the default selected at system 
generation. Bit 15 = 0 indicates the default. If bit 15 = 1, then bit 14 = 0 implies 
numeric format; bit 14 = 1 indicates alphanumeric format. 


Upon return from the call, RO contains the address of the first byte after the time 
or date string. 


Privileges Required 
None 

Macro Call 
.DATTIM 


Note that .DATTIM, like all RSTS/E-specific directives under RT-11, is not ex- 
panded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 
No errors are possible with the .DATTIM directive. 
Example 


The following program prints the current date and time at the job’s terminal: 


»MCALL -EXIT, .PRINT 

~PRIV = EMT+377 ;Prefix EMT to RSTS/E 
~-DATTIM = EMT+361 ;Date/time EMT to RT-11 
»CSECT 


START: 


DATMSG: 
DATES: 
TIMMSG: 
TIMES: 


- END 


-PRIV, .DATE Get date from RSTS/E 

MOV XRB+2,-(SP) :Save time 

MOV DATES, RO ;Set addr for ret. string 
. DATTIM ;Get date string 

CLRB (RO) + ;Clear last byte for ASCIZ 
-PRINT #DATMSG ;Print date message 

CLR XRB ;Clear date from XRB 

MOV (SP) +, XRB+2 :Set time in XRB 

MOV TIMES, RO ;Set addr for time string 
.DATTIM ;Get time string 

CLRB (RO) + ;Make string ASCIZ 

-PRINT +#TIMMSG ;Print time message 

-EXIT ;End program 

-ASCITI /The date is / 

- BLKW 12 

-ASCII /The time is / 

- BLKRW 12 
START 
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7.9 .DELETE — Delete File from Disk or DECtape 


7-22 .DELETE 


The .DELETE directive deletes a file from a disk or DECtape, deleting it from the 
device directory and releasing the space for other use. The file description given 
in the call includes a device, file name, and type. Set the PPN offset to include a 
PPN for the file, if desired (see Chapter 6). Otherwise, the PPN of the calling job 
is used. 


Note that on RSTS/E systems, unlike the RT-11 operating system, it is possible to 
delete files which are open; no error is returned. 
Privileges Required 


Write access to the file being deleted (if disk). DEVICE privilege is required if the 
device is restricted. 


Macro Call 

.DELETE area,chanum,devblk,seqnum 

where: 

area is the address of a three-word argument block. 

chanum is ignored on RSTS/E systems. 

devblk is the address of a four-word device block containing the device and file 
specification. See Chapter 6 for the format of this area. See also the PPN 
offset description for specifying a PPN. 

seqnum is ignored on RSTS/E systems. 


Argument Block Format 


~«— (RO) 


ccs 
devblIk 


Errors 


Code Meaning 

1 The file named cannot be found. 

2 The device specified is not a disk or DECtape. 

Example 

The following code deletes the file name FILNAM.TYP in the user’s account on 
disk unit 1: 


AREA: - BLKW 3 
DEVBLK: -RADSO /DK1FILNAMTYP / 


.DELETE #AREA, #1, #DEVBLK 


7.10 .DOCCL — Doa RSTS/E .CCL 


This directive lets a program running under control of the RT-11 run-time system 
examine a string to see if it is a valid RSTS/E Concise Command Language (CCL) 
command. 


NOTE 


.DOCCL must be used by programs running under the RT-11 run-time 
system, rather than the general monitor .CCL command. 


If the string is a valid CCL command, the RT-11 run-time system restores the low 
512. bytes of memory to what the monitor expects and issues a general monitor 
.CCL command. (See Chapter 3 for a description of .CCL.) 


The starting address of the string to be examined is passed in RO. The string 
itself must be in ASCIZ format (terminated with a zero byte). 


Privileges Required 


Execute access to the program that the CCL command executes. 


Macro Call 
.DOCCL 


Note that .DOCCL, like all RSTS/E-specific directives under RT-11, is not ex- 
panded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 


The errors returned for .DOCCL are the same (and in the same format) as for 
.CCL. 


Example 


The following code executes the CCL command PIP: 


.DOCCL = EMT+367 

STG: .ASCIZ /PIP/ 
MOV #STG, RO 
.DOCCL 
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7.11 .DOFSS — Do a RSTS/E .FSS 


7-24 .DOFSS 


The .DOFSS directive examines a string to see if it is a valid RSTS/E file 
specification. The RT-11 emulator restores the low 512. bytes of memory to what 
the monitor expects and executes a .FSS directive. 


NOTE 


You must use .DOFSS rather than .FSS for a program running under 
the RT-11 run-time system. 


The .DOFSS directive assumes that RO contains the starting address of the 
string and that the string itself is in ASCIZ format (terminated with a zero byte). 
See the discussion of .FSS in Chapter 3 for an explanation of how the string is 
processed. The data returned on completion of .DOFSS is the same as for .FSS. 


Note that .DOFSS, like all RSTS/E-specific directives under RT-11, is not 
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Privileges Required 

None 

Macro Call 

.DOFSS 

Errors 

The errors for .DOFSS are the same (and in the same format) as for .FSS. 
Example 


The following code checks the string FILE.NAM to see if it is a valid RSTS/E file 
specification: 


.DOFSS = EMT+365 

STG: .ASCIZ /FILE.NAM/ 
MOV #STG, RO 
.DOFSS 


7.12 .DORUN — Chain to Non-RT-11 RTS Program 


Use the .DORUN directive to transfer control to programs that run under a 
non-RT-11 run-time system. 


NOTE 


The .DORUN directive must be used from programs running under the 
RT-11 run-time system, rather than the .RUN directive, since RT-11 
keeps user logical information in a different area in low-core than the 
monitor expects. 


The .DORUN directive causes the emulator to restore the user logical information 
to its normal place in the low 512. bytes of memory and translates an RT-11 file 
specification to the proper form in the FIRQB for a .RUN. 


The .DORUN assumes that RO contains the address of a five-word file definition. 
The first four words contain a normal RT-11 "device block" specification (see 
Chapter 6); the last word contains a parameter to be passed to the run-time 
system at FIRQB+FQNENT. If the address passed in RO points to a device 

block within an outspec area returned by a previous .CSISPC directive, all of 

the RSTS/E-specific information from the file specification (PPN, and so forth) 

is loaded into the proper area in the FIRQB. Values in the first six words of the 
scratch pad area take precedence over the values found in the string examined by 


.CSISPC. 


Privileges Required 


Execute access to the specified program. 


Macro Call 
.DORUN 


Note that .DORUN, like all RSTS/E-specific directives under RT-11, is not ex- 
panded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 


Errors are returned as for a .RUN directive. 


Example 


The following program uses .CSISPC to scan a user-entered file specification, 
ensures that the program is entered with a zero parameter passed to the run- 
time system, and then attempts to execute the file with .DDORUN. If an error 
occurs for either the .CSISPC or the .DORUN, an error message is printed at the 
job’s terminal. The code follows: 


-SETFQB = EMT+360 ;Define EMT for SETFOQB 
-DORUN = EMT+363 ;Define EMT for .DORUN 
-CSISPC OUTSPC, DEFEXT,O ;Read, scan command string 
BCS ERROR ;Command string in error 
MOV OUTSPC, RO 7;Get devblk for first file 
CLR 4*2 (RO) 7;Pass 0 at FIROB+FONENT 
. DORUN ;Try to run the file 
ERROR: -PRINT #ERRMES ;An error occurred 
-EXIT 
ERRMES: -ASCIZ /?Can’t run that file/ 
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7.13 .DSTATUS — Return Device Status 


The .DSTATUS directive returns information about a device to a four-word area 
defined in the user program. 


Privileges Required 


None 

Macro Call 

.DSTATUS stablk,deunam 

where: 

stablk is the address of a four-word area to contain the returned status informa- 
tion. 

devnam is the address of one word containing a device and unit number, in RAD50 
format. The word can also be a three-character user logical name in RAD50 
format. 


Information Returned to Statbik 


status word (see format) 
handler size (= 0 for RSTS/E) 
load address (=160000 for RSTS/E) 


device size (= 0 for RSTS/E) 


Status Word Format 


| flags handler index 


The low byte contains the RT-11 handler index for the device: 


Octal 

Value Device 

0 (disk) 

1 DT (DECtape) 

3 LP (line printer) 

4 KB (keyboard) 

7 PR (paper tape reader) 
10 PP (paper tape punch) 
11 MT (magnetic tape) 

14 CR (card reader) 
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The high byte describes the device characteristics. Note that you can combine the 
device-characteristics flags. For example, a value of 140000 for the entire word 
would indicate a file-structured, read-only disk. The word values are: 


Device Characteristics Meaning 


(Octal Word Value) 

100000 Device is file-structured 
040000 Device is read-only 
020000 Device is write-only 
Errors 


Code Meaning 


0 The device named in the deunam argument is not known on the system. 


Example 


The following code checks for status information for MTO: 


STAT: - BLKW 4 
DEVNAM: »RAD50 /MTO/ 
~-DSTATUS #STAT, #DEVNAM 
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7.14 .ENTER — Open File for Output 


7-28 .ENTER 


The .ENTER directive creates a new file and associates the file with a channel 
number. You then use the channel number to refer to the file for other I/O 
operations. | 


A RSTS/E "tentative open" is done; that is, the file is not permanent until a 
.CLOSE is executed with the same channel number as specified in the .ENTER 
directive. Then, the tentative file is made permanent, and any already existing 
file of the same name on the same device is deleted. A .PURGE, .HRESET, or 
.SRESET directive deletes the tentative file; any already existing file of the same 
name on the same device is left intact. 


You can preallocate space for disk files by setting an argument in the call. Note 
that you can also set a PPN, protection code, mode, and other RSTS/E parameters 
applicable to opening a file for output by setting words in the scratch pad area 
(see Chapter 6). 


Privileges Required 
Write access to the file. 


Macro Call 


ENTER area,chanum,devblk,len,seqnum 


where: 

area is the address of a four-word argument block. 

chanum is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on 
channel numbers. 

devblk is the address of a four-word device-block containing the device and file 
specifications. See Chapter 6 for the format of this area. 

len is the file size to be preallocated for the file, in 512-byte blocks (for disk files 
only). Values can range from 1 to 32767. For large disk files on RSTS/E, you 
must set the Most Significant Bits (MSB) byte in the scratch pad area (see 
Chapter 6). RSTS/E ignores a zero or negative value. 

seqnum is ignored on RSTS/E systems. 


Argument Block Format 


devblk 
[seamen 


Errors 


Code Meaning 
0 Channel is already in use. 


1 The file cannot be preallocated to the specified size, or the device is full. 


Example 
The following code opens the file NEWFIL.SAV on MTO0 for output: 


AREA: - BLKW 4 
DEVBLK: » RAD50 /MTONEWFILSAV/ 


.ENTER #AREA, #1, #DEVBLKE, #0, #0 
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7.15 .ERRPRT — Print RSTS/E Error Message 


7-30 .ERRPRT 


The .ERRPRT directive prints the RSTS/E error message text corresponding to 
an error code on the user terminal. The call assumes that the error code is in RO. 
The text is printed without a carriage-return/line-feed combination. 


Privileges Required 


None 


Macro Call 
ERRPRT 


Note that .ERRPRT, like all RSTS/E-specific directives under RT-11, is not ex- 
panded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 
No errors are possible with the .ERRPRT directive. 


Example 


-MCALL -EXIT, .PRINT, .REGDEF 
- REGDEF 


»-ERRPRT = EMT+364 


.CSECT 
START: MOV 256.,R1 ;Number of errors to print 
CLR RO ;Start with error zero 
10S: - ERRPRT ;Print error text 
MOV RO, - (SP) ;Save RO 
-PRINT #CRLF ;Print a CRLF 
MOV (SP) +, RO ;Restore RO 
INC RO ;Inc RO for next message 
SOB R1,108 ;Loop until all are printed 
~EXIT 
CRLF : - BYTE 0 
- END START 


7.16 .EXIT — Program Exit 


The .EXIT directive terminates execution of the calling program. On exiting from 
the calling job, the RSTS/E monitor drops any temporary privileges still in effect. 
Then, control passes to the job keyboard monitor at the keyboard monitor entry 
point (see P.NEW in Chapter 2). 


NOTE 


The job keyboard monitor is the default keyboard monitor unless the 
job has issued the SET JOB/KEYBOARD_MONITOR command or has 
issued a general monitor .RTS directive (see Chapter 3) to specify a job 
keyboard monitor. 


If RO = 0 when the .EXIT is executed, any channels still open will be released, 
without the usual clean-up operations. In particular, any temporary files (opened 
with .ENTER and not yet closed) will be deleted. 


NOTE 


Programs running under the RT-11 run-time system must use the 
RT-11 .EXIT directive, not the general monitor .EXIT or .RTS directive. 


Privileges Required 
None 


Macro Call 
EXIT 


Errors 


No errors are possible with the .EXIT directive. 


Example 


The following code exits such that files opened with .ENTER and not yet closed 
will be deleted: 


SAVOLD: MOV #0, RO 
EXIT 
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7.17. .FETCH — Check Whether Device Exists 


1-32 


-FETCH 


On RSTS/E systems, the .FETCH directive checks to see if a specified device 
exists on the system. 


Privileges Required 


None 

Macro Call 

FETCH addr,deunam 

where: 

addr is ignored on RSTS/E. 

deunam is the address of a one-word, RAD50 device name. The format of this 
word is the same as that described for the first word of a device block (see 
Chapter 6). 

Errors 


Code Meaning 


0 The device specified does not exist on the system. 


Example 


The following code checks to see if LPO exists on the system: 


DEVNAM: -RAD50 /LPO/ 


»- FETCH #0, #DEVNAM 


7.18 .GETCOR — Changes Job Image Size 


This directive changes the amount of space currently allocated for the user job 
image. The RT-11 emulator checks to ensure that the requested expansion will 
not destroy the scratch pad area, moves the scratch pad area if necessary, and 
then expands the job image size using the .CORE directive (see Chapter 3). Thus, 
the same rules concerning size changes for .CORE also apply to .GETCOR. 


The .GETCOR directive assumes that the new job image size, in K words, is in 
RO. If the required expansion is not possible, the carry bit will be set on return 
from the call. Otherwise, the size change succeeds, and word 44 now points to 

the new location for the start of the scratch pad area. 


NOTE 


Programs running under the RT-11 run-time system must use 
.GETCOR, not the general monitor .CORE directive. 


You must use .GETCOR to expand the job image size before you use 
.CHAIN to transfer control to a program that requires more memory 
than the current program. 


Privileges Required 


EXQTA privilege is required to exceed the job’s memory limit. 


Macro Call 
.GETCOR 


Note that .GETCOR, like all RSTS/E-specific directives under RT-11, is not 
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 


If the requested change cannot be made, the carry bit is set on return from the 
call. 


Example 


The following code uses .GETCOR to expand the user job image area to 24K 
words before doing a .CHAIN: 


-GETCOR = EMT+366 


MOV #24.,R0 


- GETCOR 
BCS ERRTN 
. CHAIN 
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7.19 .GTIM — Return Time-of-Day 


7-34 .GTIM 


The .GTIM directive returns the current time of day to a two-word area defined 
by the user program. The current time is given in units of 1/60th second since 
midnight. 


Privileges Required 


None 

Macro Call 

.GTIM area,timblk 

where: 

area is the address of a two-word argument block. 

timblk is the address of a two-word block where the time is to be returned. The 


first word will contain the Most Significant Bits (MSB) of the current time, 
and the second word the Least Significant Bits (LSB). 


Argument Block Format 


Tae] <tr 


Errors 


No errors are possible with the .GTIM directive. 


Example 


The following code returns the current time to a two-word area named TIME: 


AREA: - BLKW 2 
TIME : - BLKW 2 
-GTIM 


7.20 .GTJB — Return Job High Limit 


The .GTJB directive on RT-11 systems returns job parameters to an eight-word 
area in memory. On RSTS/E systems, the only relevant parameter is the job’s 
high memory limit. All other words are set to zero. 


Privileges Required 


None 

Macro Call 

.GTJB area,addr 

where: 

area is the address of a two-word argument block. 

addr is the address of an eight-word block to which the job parameters are 


returned. On RSTS/E systems, only the second word is relevant: it is set to 
the high memory limit of the user job image. All other words are set to zero. 


Argument Block Format 


Errors 


No errors are possible with the .GTJB directive. 


Example 


The following code stores job information in an area called JOBINF: 


AREA: . BLKW 2 
JOBINF: . BLKW 8. 
.GTUB #AREA, #JOBINF 
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7.21 .GTLIN — Get Line from Job’s Terminal 


7-36 .GTLIN 


The .GTLIN directive accepts a line of input from either the job’s terminal or core 
common and stores it in a buffer for later examination by the user program. You 
can also specify an ASCIZ string to be displayed at the terminal before the line is 
accepted. 


-GTLIN reads the line from core common instead of the job’s terminal if the 
program is invoked with a parameter word of 8192. For example, the parameter 
word normally has this value when a program is run by a CCL command. A 
second .GTLIN causes the program to exit. 


By default, .GTLIN returns a string in uppercase. To obtain lowercase letters, set 
bit 14 in the Job Status Word (JSW) before you issue the .GTLIN. 


Privileges Required 


None 

Macro Call 

.GTLIN linbuf L,prompt] 

where: 

linbuf is the address of an area to receive the input line. Up to 81 bytes can be 
accepted from a terminal, so the buffer should be at least that long. The 
line is stored in memory and terminated with a zero byte instead of with a 
carriage-return/line-feed combination. 

prompt is the address of a string to be printed on the job’s terminal before input 
is accepted. The string itself must be terminated with a zero byte or a 200 
(octal) byte. If the string is terminated with a zero byte, the display ends 
with a carriage-return/line feed. If terminated with a 200 (octal) byte, the 
display ends after the prompt string. 

Errors 


No errors are possible with the .GTLIN request. 


Example 


The following example prompts the job’s terminal and accepts a line of input: 


PROMPT: ~-ASCIZ /YES OR NO?/ 
LINBUF: - BLKB 81. 
-GTLIN #LINBUF, #PROMPT 


7.22 .GVAL — Get Value from Scratch Pad 


The .GVAL directive returns the contents of a word in the scratch pad area to RO. 
You specify an offset from the beginning of the scratch pad. 


Privileges Required 


None 

Macro Call 

-.GVAL area, offset 

where: 

area is the address of a two-word argument block. 

offset is the offset, in bytes, from the beginning of the scratch pad area of the 


word desired. The offset. value must be even. An odd offset causes a trap to 
kernel mode vector at four. 


Argument Block Format 


[2] <1 
eee 


Errors 


Code Meaning 
0 The offset given is beyond the limits of the scratch pad area. 


Example 


The following example returns the contents of the PROTEC offset in the scratch 
pad area to RO: 


AREA: - BLKW 2 


.GVAL #AREA, #2 
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7.230 -HRESET — Hardware Reset 


7-38 .HRESET 


The .HRESET (hardware reset) directive closes all open channels for the program 
without performing any of the normal clean-up operations (except to disassociate 
the RT-11 channel numbers from their RSTS/E counterparts). For example, no 
trailer labels are written to magnetic tape, no form feed is given for the line 
printer, and so forth. Temporary files (created with .ENTER but not yet closed) 
are deleted. 


Privileges Required 


None 


Macro Call 
HRESET 


Errors 
No errors are possible with the .HRESET directive. 


Example 


- HRESET 


7.24 .LOOKUP — Open File for Input 


The .LOOKUP directive opens an existing file and associates it with a channel 
number; in RSTS/E terms, an OPEN FOR INPUT statement. The channel used 
is then busy until one of the following directives is executed: 


.CLOSE 

SAVESTATUS 

SRESET 

-HRESET 

PURGE 

.CSIGEN (Gf the channel number is in the range 0 to 8) 


Note that you can set a PPN applicable to a RSTS/E OPEN FOR INPUT 
statement by setting the appropriate words in the scratch pad area before 
executing the .LOOKUP (see Chapter 6). 


Privileges Required 


For disk files, you need read access. If the device is restricted, you need DEVICE 
privilege. You need RDNFS privilege to access disks in non-file-structured mode. 


Macro Call 
.LLOOKUP area,chanum,devblk,seqnum 


where: 

area is the address of a three-word argument block. 

chanum is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on 
channel numbers. 

devblk is the address of a four-word device block containing the device and file 
specifications. See Chapter 6 for general rules on the format of device 
blocks. 
The file name portion of the device block is ignored for non-file-structured 
devices, such as a paper tape. If you want to do non-file-structured I/O on 
a file-structured device, clear the first word of the file name portion of the 
device block. 

seqnum is ignored on RSTS/E systems. 


Argument Block Format 


= (9 
devblik | 
Errors 
Code Meaning 
0 Channel already open. 
1 The file requested (in the device block) was not found. 
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7-40 .LOOKUP 


Example 


ERRBYT=42 

ARGBLK: .BLKW 

DEVBLK: .RAD50O 
»-RAD50 


- LOOKUP 
BCC 
TSTB 
BNE 
~-PRINT 
~-EXIT 
NFD: -PRINT 
~-EXIT 
CAMSG: ~-ASCIZ 
NFMSG: ~ASCIZ 


5 ;leave space for arg block 
/DT3/ ;Define device, 
/DATA OO1/ ;Filename and type 


#ARGBLK,#7,#DEVBLK ;Open on channel 7 


LDONE ;File was found 

@#ERRBYT ;Error--test further below 
NFD ;File not found 

+#CAMSG ;Print '/Channel Active’ 
#NEFMSG ;PRINT /File not found’ 


/Channel active/ 
/File not found/ 


7.25 .PRINT — Display String on Job’s Terminal 


The .PRINT directive displays a specified ASCII string on the job’s terminal. The 
line can be terminated with or without a carriage-return/line-feed combination. 
Note that on RSTS/E systems, if the terminal is detached when a .PRINT is 
issued, the job hibernates. That is, execution of the job is suspended until the 
terminal is reattached to the job. 


Privileges Required 


None 

Macro Call 

PRINT stradd 

where: 

stradd is the starting address of the string to be printed. The string itself must be 
terminated with either a zero byte or a byte value of 200. If the string is 
terminated with a zero byte, the display ends with a carriage-return/line- 
feed combination. If the string is terminated with a 200 byte, the display 
ends with the string. 

Errors 


No errors are possible with the .PRINT directive. 


Example 
$l:  .ASCIZ /String will have CR-LF following/ 
S2:.  .ASCII /String will have no CR-LF following/ 
| ; -BYTE 200 
- EVEN 
»-PRINT #S1 
-PRINT #S2 
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7.26 .PURGE — Release Channel 


7-42 


-PURGE 


The .PURGE directive can be used to release a channel when it is not desirable to 
close the file normally. Any temporary file created by a .ENTER is discarded. A 
.PURGE on a file that was opened with .LOOKUP will cause no action other than 
to free the channel; any data written to the file will still be there. If the specified 
channel is not open, the .PURGE is simply ignored; no error is returned. 
Privileges Required 


None 


Macro Call 
-PURGE chanum 


where: 

chanum is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on 
channel numbers. 

RO Format 

Errors 


No errors are possible with the .PURGE directive. 


Example 


The following example verifies that channels 0 to 7 are free: 


. TITLE - PURGE ..MAC 
-MCALIL -PURGE, .EXIT 
START: 
CLR R1 ;Start with channel O 
1s . PURGE R1 ;Purge a channel 
INC Rl ;Bump to next channel 
CMP R1, #8. ;Is it at channel 8 yet 
BLO 1s 
- EXIT 
»- END START 


7.2/7 .RCTRLO Reset Ctrl/O 


The .RCTRLO directive restarts any programmed output to the user’s terminal 
after such output has been stopped by the user-entered Ctrl/O or Ctrl/C. 


Terminal service on RSTS/E maintains a "discard all program output’ indicator 
for each terminal on the system. When this indicator is set, the driver ignores 
any output requests for that terminal. When the indicator is clear, output to the 
terminal proceeds normally. The .RCTRLO directive clears this indicator. 


The driver sets the indicator when the user enters a Ctrl/C or Ctrl/O combination 
and reverses it when the user enters a Ctrl/O again. 


Thus, when it is important that a message get through to the terminal, use a 
.RCTRLO directive before the .PRINT or other request for output to make sure 
that the message is displayed regardless of any user-entered Ctrl/O or Ctrl/C. 


Privileges Required 
None 


Macro Call 
-.RCTRLO 
Errors 


No errors are possible with the .RCTRLO directive. 


Example 


The following example forces the message to be displayed on the user’s terminal: 


EOW: -ASCIZ /The end of the world is nigh/ 
-RCTRLO 
-PRINT #EOW 
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7.28 .READ/.READW/.READC — Read Data 


On RSTS/E systems, .READ, .READW, and .READC transfer data from a file 
or device previously opened on a channel to a user buffer. Once the transfer is 
complete, control returns to the user program inline, for .READ and .READW, 
or to a user-specified completion routine, for .READC. You specify the maximum 
number of words to be transferred; the actual number of words transferred is 
returned in RO. 


Note that you can set a modifier word in the scratch pad area for devices that use 
this information. See the .READ directive in Chapter 3 for possible values of the 
modifier word. 


Privileges Required 


None 


Macro Call 


.READ 


area,chanum,bufadd,wrdcnt,blknum 
.READW 


or 


-READC area,chanum,bufadd,wrdcni,cmprtn, blknum 


where: 

area is the address of a five-word argument block. 

chanum is a channel number in the range 0 to 17 (octal), previously defined in an 
open (.LOOKUP). 

bufadd is the address of a buffer to contain the data to be read. 

wrdcent is the maximum number of words to be read. The actual number of words 
read may be less than wrdcnt; it is never more. The actual number of words 
transferred is returned in RO. 

emprtn is the address of a completion routine to which control is transferred when 
the read is complete. (For .READC only.) 

blknum is the block number relative to the start of the file where the read is to 


begin (for files opened with file-structured .LOOKUP). To access large files 
on RSTS/E systems, you must set the word at offset 2 in the scratch pad 
area; see Chapter 6. For devices opened with non-file-structured .LOOKUP, 
blknum is the absolute block number or device cluster number where the 
read is to begin. 


For successive reads, your program must increment blknum. 


7-44 .READ/.READW/.READC 


Argument Block Format 


* (The last word = 0 for .READW, or 1 for .READ.) 


Errors 


Code Meaning 


0 Attempt to read past end-of-file (EOF). 
1 Hard error occurred on channel. 

2 Channel is not open. 

Example 


The following code reads data from the device open on channel 7 to a 512. byte 
user buffer: 


AREA: - BLKW 5 
BUF: - BLKW 512. 
- READ #AREA, #7, #BUF, #512., #0 
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7.29 .RENAME — Rename a File 


7-46 .RENAME 


The .RENAME directive changes the name of a file on disk or DECtape and 
gives that file the current date in its directory entry. If a file with the new name 
already exists on the specified device, it is deleted. 


Privileges Required 


If the device is restricted, you need DEVICE privilege. For disk files, you need 
create/rename access to the file. 


Macro Call 
RENAME area,chanum,namblk 


where: 

area is the address of a two-word argument block. 

chanum is ignored on RSTS/E systems. 

namblk is the address of an eight-word area containing two four-word device and 


file descriptor blocks (see Chapter 6). The first four-word block is the old 
file name and the device where it is stored. The second four-word block 

is the new file name; the device descriptor must be specified, and must be 
the same as the device descriptor in the first four-word block. If a PPN is 
specified in the first six words of the scratch pad, it is used for both the old 
and the new file. If a protection code is given in the first six words of the 
scratch pad, it is used for the new file. Other values in the first six words of 
the scratch pad are ignored. 


Argument Block Format 


devbik 


<< (RO) 


Errors 


Code Meaning 
1 No file with the "old" name was found on the device. 
2 The device specified is not a disk or DECtape. 


Example 
The following code renames file OLDFIL.MAC to NEWFIL.MAC: 


AREA: - BLKW 2 
NAMBLE: » RAD50 /DT3/ 
-RAD50 /OLDFIL/ 
- RAD50 /MAC/ 
» RAD50 fDIS/ 
-RAD50 /NEWFIL/ 
»RAD50 /MAC/ 


.RENAME #AREA, #0, #NAMBLK 


7.30 .REOPEN — Reopen File Closed with .SAVESTATUS 


The .REOPEN directive reopens a file that was closed with a SAVESTATUS 
directive. You can use a different channel number than was used in the original 
LOOKUP and SAVESTATUS, as long as the new channel is not already open. 


The SAVESTATUS and .REOPEN directives are easier to use than .CLOSE and 
.LOOKUP, if your program needs to open more than 15 files during its execution. 
The .SAVESTATUS directive retains the information necessary to reopen a file, 
including the PPN. Thus, you do not need to reset the PPN offset in the scratch 
pad area. 


Privileges Required 


If the device is restricted, you need DEVICE privilege. You need RDNFS privilege 
to access a non-file-structured disk. You need read access to the file. 


Macro Call 
REOPEN area,chanum,chnblk 


where: 

area is the address of a two-word argument block. 

chanum is a free channel number in the range 0 to 17 (octal). See Chapter 6 for 
rules on channel numbers. 

chnblk is the address of the five-word block where the channel status information 


was stored (see SAVESTATUS). 


Argument Block Format 


pe chanum | ~<€ (RO) 

| chnblk 

Errors 

Code Meaning 

0 The specified channel is in use. The .REOPEN has not been done. 


Example 


The following code reopens a file closed with SAVESTATUS using the device 
block area named SAVBLE: 


AREA: - BLEW 2 
SAVBLK: - BLKW ha) 


.REOPEN #AREA, #6, #SAVBLK 
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7.31 .SAVESTATUS — Save Status of File for Later .REOPEN 


The .SAVESTATUS directive closes a disk or DECtape file, saving all the 
information needed to reopen the file later in execution of the program (see 
-REOPEN). The information saved is stored in a five-word area in the user 
program and includes the PPN for the file. Thus, the SAVESTATUS/.REOPEN 
combination is easier to use on RSTS/E systems than .CLOSE/.LOOKUP in this 
case; you do not have to set the PPN offset in the scratch pad area. 


The .SAVESTATUS directive can be used only if the file was opened with 
-.LOOKUP. If the file was opened with .ENTER, a .SAVESTATUS on that channel 
returns an error. 


Privileges Required 


None 

Macro Call 

SAVESTATUS area,chanum,chnblk 

where: 

area is the address of a two-word argument block. 

chanum is a channel number in the range 0 to 17 (octal), previously used in a 
.LOOKUP directive for disk or DECtape. 

chnblk is the address of a five-word area to store the current information for the 


file. On RSTS/E systems, the first four words of this area are set to the 
device, file name, and type, in the standard RT-11 device-block format (see 
Chapter 6). The last word of this area is set to the PPN of the file. 


Argument Block Format 


chnblk 


Errors 


Code Meaning 


0 The channel specified is not currently open; that is, a previous .LOOKUP on the 
channel was never done. 


1 The file was opened with .ENTER, or else the file is not on a disk or DECtape 
device. The .SAVESTATUS is illegal. 


Example 


The following code saves the status of the file open on channel 12 for a later 
reopen: 


AREA: - BLKW 2 
SAVBLK: - BLKW 5 


.SAVEST #AREA, #12.,#SAVBLK 
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7.32 .SCCA — Pass Ctri/Z to User Program 


The .SCCA directive lets a user program recognize and process a Ctrl/Z combina- 
tion entered on the job’s terminal. When called with any nonzero value for the 
addr argument, subsequent Ctrl/Zs entered at the job’s terminal are translated 
to an ASCII 3 and passed like any other character to the program when it issues 
a .TTYIN or .GTLIN. (Normally, a Ctrl/Z causes the RT-11 emulator to exit the 
running program when a .READ or .TTYIN is done.) 


NOTE 


The operation of the .SCCA directive is quite different under RSTS/E 
than under the RT-11 operating system, where it lets a user program 
trap Ctrl/C combinations. 


The .SETCC directive must be used for this function under the RT-11 
run-time system under RSTS/E. The intent is to let you code an 
.SCCA directive to trap the delimiter equivalent in function on the two 
systems. 


On RSTS/E systems, Ctrl/Z is the "type-ahead terminator." You can, for example, 
type RUN $MACRO, type the command line for the assembly, enter a Ctrl/Z, and 
then type RUN $LINK. You do not have to wait for the assembly to finish before 
typing the command to link. 


On RT-11 systems, Ctrl/C is the "type-ahead terminator." Hence, the .SCCA 
directive processes the character appropriate to the system on both RSTS/E and 
RT-11 systems. 


Privileges Required 


None 

Macro Call 

OCCA area,addr 

where: 

area is the address of a two-word argument block. 

addr is a switch. Any nonzero value for this argument causes Ctrl/Zs to be passed 


to the user program, as described previously. A zero value returns Ctrl/Z 
processing to the emulator. 


Argument Block Format 


Errors 


No errors are possible with the .SCCA directive. 
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Example 


The following code causes Ctrl/Zs to be passed to the program: 


AREA: - BLKW 2 


.SCCA #AREA, #1 
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7.33 .SETCC — Process Ctrl/C 


The SETCC directive defines a routine to be entered when the user enters one 
Ctrl/C on the job’s terminal. (Two consecutive Ctrl/Cs still aborts the running 
program.) The address of the routine to be entered is assumed to be in RO when 
the SETCC is executed. 


The .SETCC is only effective until the first Ctrl/C; you must reissue the SETCC 
from the trap routine if you want it to remain in effect. You must also reenable 
Ctrl/O processing with .RCTRLO. Use an RTI instruction to exit from the trap 
routine. See the discussion of offset 66 in the scratch pad area in Chapter 6 for 
further information on Ctrl/C processing under the RT-11 run-time system. 


Privileges Required 


None 


Macro Call 
SETCC 


Note that .SETCC, like all RSTS/E-specific directives under RT-11, is not ex- 
panded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 


Errors 
No errors are possible with the .SETCC directive. 


Example 


The following code defines a routine to be entered when the user enters a Ctrl/C 
on the job’s terminal: 


-SETCC = EMT+362 


MESAGE: .ASCIZ "You typed a Ctrl/c!" 
MOV #CTLC, RO 
- SETCC 
CTLC: » RCTRLO 
-PRINT #MESAGE 
MOV #CTLC, RO 
- SETCC 
RTI 
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7.34 .SETFQB — Set Up FIRQB 


7-52 .SETFQB 


The .SETFQB directive can be used after a .CSISPC; the two calls combined 
return information to the FIRQB and XRB as if the file specification string had 
been examined by .FSS. 


The call assumes that RO contains the address of the first word of a device block 
returned by .CSISPC. As noted in the discussion of .CSISPC, the device-block 
information must not have been moved; thus, the address in RO must be the 
address of the first word of a device block within the "outspc" area returned by 
the last .CSISPC. 


Note that any information in the first six words of the scratch pad area overrides 
any RSTS/E-specific information returned by the .CSISPC. In addition, the 
SETFQB clears the first six words of the scratch pad after using the information. 


Privileges Required 


None 


Macro Call 
SETFQB 


Note that .SETFQB, like all RSTS/E-specific directives under RT-11, is not 
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a 
directive.) You can code a definition of the directive in a data section of your 
program or use .MACRO to define it. See the following example. 

Errors 


No errors are possible with the .SETFQB directive. 


Example 


The following code returns information to the FIRQB and XRB about the file 
following the equal sign (=) in an RT command: 


.-SETFQB = EMT+360 
-CSISPC #OUT, #EXT, #CMD 


MOV #OUT+<3*5%*2>,R0 
. SETFQB 


7.35 .SETTOP — Expand to Start of Scratch Pad 


On RSTS/E systems, the .SSETTOP directive sets the contents of the word at 
location 50 in the low 512 bytes of memory to the value specified in .SETTOP. 
The value itself cannot equal or exceed the starting address of the scratch pad 
area (see Chapter 6). If such a value is specified, SETTOP simply sets the 
contents of location 50 to the address of the first word after the starting address 
of the scratch pad. The value actually set in word 50 is also returned to RO on 
completion of the call. 


Privileges Required 
None 


Macro Call 

SETTOP adrval 

where: 

adrval is a value specifying the address to which location 40 is to be changed. 
Errors 

No errors are possible with the .SSETTOP directive. 

Example 


The following code sets the contents of location 50 to the address of the word after 
the start of the scratch pad: 


-SETTOP #-2 
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7.36 .SFPA — Set Floating-Point Error Address 


7-54 .SFPA 


The .SFPA directive indicates that you want to handle floating-point errors 
yourself. You specify the address of a routine to be entered if such errors occur. 
The .SFPA works for errors on both the FIS (floating-point instruction set on 
the PDP-11/35 and 11/40) and the FPP or FPU (hardware floating-point units 
compatible with the PDP-11/45 and 11/70 asynchronous unit) and its equivalents. 
In the case of FPP or FPU hardware, two words have been pushed on the stack: 
the Floating-Point Exception Code (FEC) at the top of the stack and the Floating 
Error Address (FEA) one word down. Your routine can process these words in 
any way it sees fit and should pop them from the stack before issuing an RTI 
instruction to return control to the program where it left off when the errors 
occurred. 


The .SFPA directive works only for one floating-point error trap. You must 
reexecute the .SFPA from your error-processing routine to ensure that successive 
errors are handled in the same way. You can disable traps to your error routine 
by issuing the .SFPA directive with a zero address argument. 


NOTE 


You should not use .SFPA in a routine called by a FORTRAN program, 
because programs compiled under FORTRAN have their own FPP/FIS 
exception handling routines and expect to find the FPU status as they 
have set it. 


Privileges Required 


None 

Macro Cail 

.SFPA area,addr 

where: 

area is the address of a two-word argument block. 

addr is the address of the routine to be entered when a floating-point error occurs. 


Argument Block Format 


Errors 


No errors are possible with the .SFPA directive. 


Example 


The following code defines ERRTN as the address of the error routine to be 
entered when a floating-point error occurs: 


AREA: - BLRW 2 


.SFPA #AREA, #ERRTN 


7.37. .SPFUN — Special Functions for 1/O 


The .SPFUN directive handles special functions for disk, terminal, magnetic tape, 
and flexible diskette. 


Privileges Required 


None 


Macro Call 


SSPFUN area,chanum, func, buf [went] [,6/k]Lcrin] 


where: 


area 


chanum 


func 


buf 


went 


blk 


crtn 


is the address of a six-word argument block. 


is a channel number in the range 0 to 17 (octal), defining the device on 
which the special function is to be performed. The channel must have been 
previously opened with .LOOKUP. 


is a special function code. To request magnetic tape special functions 
emulating RT-11’s .SPFUN, set this argument to one of the following values: 


377 Write end-of-file 

376 Forward 1 record 
375 Backspace 1 record 
373 Rewind to load point 
372 Offline rewind 


Any other value for this argument is used as the function code (at 
XRB+XRLEN) in a RSTS/E .SPEC directive (see Chapter 3). 


is used as the value of the word at XRB+XRLOC in a RSTS/E .SPEC 
directive. It must be set to zero if the func argument is 377, 376, 375, 373, 
or 372. 


is used as the value of the word at XRB+XRBC in a RSTS/E .SPEC directive. 
It is ignored (and can be omitted) if the func argument is 377, 376, 375, 373, 
or 372. 


is used as the value of the word at XRB+XRBLK in a RSTS/E .SPEC 
directive. It is ignored (and can be omitted) if the func argument is 377, 
376, 375, 373, or 372. 


is the address of a completion routine to which control is to be transferred 
when the operation is complete. If this argument is omitted, control returns 
to the instruction following the .SSPFUN when the operation is completed. 


Note that if you are using .SPFUN to do a RSTS/E .SPEC, the RT-11 emulator 
fills in the RSTS/E channel number and device handler values in the XRB for 


you. 


Argument Block Format 


chanum 
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7-56 .SPFUN 


Errors 


Code Meaning 


0 Tried to read past end-of-file. 

1 Hard error occurred on channel. 
2, Channel is not open. 

Example 


The following code rewinds a magnetic tape (open on channel 4): 


AREA: - BLKW 6 


. SPFUN #AREA, #4, #373, #0 


7.38 .SRESET — Software Reset 


On RSTS/E systems, the .SRESET directive does the same thing as a hardware 
reset (HRESET). It closes all open channels for the program without performing 
any of the normal clean-up operations (except to disassociate the RT-11 channel 
numbers from their RSTS/E counterparts). For example, no trailer labels are 
written to magnetic tape, no form feed is given for the line printer, and so forth. 
Tentative files (created with ENTER but not yet closed) are deleted. 


Privileges Required 


None 


Macro Call 
SRESET 


Errors 
No errors are possible with the .SRESET directive. 


Example 


- SRESET 


SRESET 7-57 


7.39 .TRPSET — Intercept Traps to 4 and 10 


7-58 .TRPSET 


The .TRPSET directive allows the user program to trap to a user routine on 
errors that normally cause the program to abort execution. Control passes to the 
address specified in the call when the job tries to execute a reserved instruction 
(normally trapped to kernel mode address 10) or issues an instruction with an 
odd address (normally trapped to kernel mode address 4). 


The carry bit indicates which error occurred. When control is passed to the 
error-handling routine, the carry bit is zero if the error was an odd-address 
error. If the carry bit is one, the error was a reserved-instruction error. An RTI 
instruction will return control to the user program from the trap routine. 


Note that the .TRPSET directive affects only the next error causing such a trap. 
You must reissue the .TRPSET from your error-handling routine if you want to 
handle such errors consistently. 


Privileges Required 


None 

Macro Call 

-TRPSET area,addr 

where: 

area is the address of a two-word argument block. 

addr is the address to which control is to be passed when a reserved-instruction 


or odd-address error occurs. 


Argument Block Format 


Errors 
No errors are possible with the .TRPSET directive. 


Example 


The following code defines TRPRTN as the address of the routine to be entered 
when a reserved-instruction or odd-address error occurs: 


AREA: - BLEW 2 


-TRPSET #AREA, #TRPRTN 


TRPRTN: BCC ODDADR 
(code for reserved instruction) 


ODDADR: (code for odd address) 


7.40 .TTYIN/.TTINR — One-Characier Read From Terminal 


The .TTYIN and .TTINR directives both accept input from the job’s terminal and 
transfer one character to the low byte of RO. 


Bits 6 and 12 of the job status word (JSW) affect how the transfer is done. 


If bit 12 of the JSW = 0, the .TTYIN/.TTINR waits until a whole line has been 
typed at the job’s terminal and then transfers one character to the low byte of 
RO. Succeeding .TTYIN/.TTINR requests will then transfer remaining characters, 
including carriage return and line feed. In addition, the usual monitor processing 
for terminal input occurs: all characters typed are echoed at the terminal, and 
Ctrl/U and DELETE delete a line or a character, respectively. 


If bit 12 of the JSW = 1, ODT-mode input is done. That is, characters are 
transferred when they are available, rather than waiting for a whole line to 
be typed before passing a character to the user program. One .TTYIN/.TTINR 
transfers one character. Furthermore, characters typed are not echoed at the 
terminal, and Ctrl/U and DELETE are simply passed on to the user program. 
(Ctrl/C and Ctrl/O are processed as usual, however. Ctrl/S and Ctrl/Q are 
processed, if that option was requested for your terminal with TTYSET.) No 
ALTMODE conversion is done. 


If bit 6 = 1, control returns to the user program with the carry bit set if no 
character can be returned to the program. Note that this should only be used 
with .TTINR, and only when the program needs to perform other processing 
while waiting for terminal input. If bit 6 = 0, control does not return to the user 
program until a character can be passed to the program. 


If used, bits 6 and 12 in the JSW must be set by the user program; they are 
cleared automatically when a program terminates. 


NOTE 


Single character I/O places heavy demand on RSTS/E system resources 
and can degrade system performance. These calls are provided only for 
compatibility with RT-11. 


Privileges Required 


None 

Macro Calls 

.TTYIN [addr] 

or 

.TTINR 

where: 

addr is the address of a location where the character is to be stored, in addition 
to being stored in RO. If the address is omitted, the character is stored only 
in RO. 

Errors 


Code Meaning 


0 No character or characters are available in the monitor buffer for terminal I/O 
(only applies to .TTINR). 


-TTYIN/.TTINR 7-59 


Example 


The following code transfers one character from the job’s terminal to the low byte 
of RO: 


- TTYIN 


7-60 .TTYIN/.TTINR 


7.41 


.1 TYOUT/.TTOUTR — Transfer One Character to Job’s 
Terminal 


The .TTYOUT and .TTOUTR directives both transfer one character from the low 
byte of RO to the job’s terminal. Using .TTYOUT or .TTOUTER is slower than 
using .PRINT because they require more system overhead. Use .PRINT whenever 
possible. 


Note that on RSTS/E systems, if the terminal is detached when a .TTYOUT 
or .TTOUTR is executed, the job hibernates. That is, execution of the job is 
suspended until the terminal is reattached to the job. 


Privileges Required 


None 

Macro Call 

.TTYOUT [addr] 

or 

.TTOUTR 

where: 

addr is the address of a memory location containing the character to be printed. 
The character is loaded into RO first. When control returns from the call, 
RO still contains the character. If you omit this address, RSTS/E prints the 
character in the low byte of RO at the job’s terminal. 

Errors 


No errors are possible with the .TTYOUT and the .TTOUTR directives under 
RSTS/E. 


Example 


The following example transfers one character from the low byte of RO to the job’s 
terminal: 


PROMPT: ~-ASCII /*/ 
MOV #PROMPT, RO 
- TTYOUT 
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7.42 .TWAIT — Timed Wait 


7-62 .TWAIT 


The .TWAIT directive suspends execution of the job for a specified number of 
clock ticks: a sleep, in RSTS/E terms. 


Privileges Required 


None 

Macro Call 

.TWAIT area,addr 

where: 

area is the address of a two-word argument block. 

addr is the address of a two-word block specifying the length of time to sleep 


in units of 1/60th second. The first word contains the high-order bits; the 
second word contains the low-order bits. 


Argument Block Format 


Errors 
No errors are possible with the .TWAIT directive. 


Example 


The following code suspends program execution for 5 seconds: 


AREA: . BLKW 2 
ADDR: . BLKW 2 
CLW #ADDR 
MOV #300., #ADDR+2 


.TWAIT  #AREA, #ADDR 


7.43 .WAIT — Check for Channel Open 


On RSTS/E systems, the .WAIT directive checks to make sure that the specified 
channel is open. If not, the call returns with an error. 


Privileges Required 


None 

Macro Call 

WAIT chanum 

where: 

chanum is the channel number to be tested. The number can be in the range 0 to 17 
(octal). 

RO Format 


Error 


Code Meaning 


0 The specified channel is not open. 


Example 


The following code checks to see if channel 7 is open and branches if it is not: 


-WAIT #7. 
BCS #NOTOPN 
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7.44 .WRITE/.WRITW/.WRITC — Write Data 


7-64 


On RSTS/E systems, .WRITE, .WRITW, and .WRITC transfer data from a user 
buffer to a file or device previously opened on a channel. After the transfer is 
complete, control is passed to the user program inline, for .WRITE and .WRITW, 
or to a user-specified completion routine, for .WRITC. The number of words 
actually written is returned in RO when the call completes. 


Privileges Required 
EXTQA privilege suppresses disk quota checks when extending a disk file. 
Macro Call 
WRITE 
area,chanum, bufadd,wrdcnt,blknum 
.WRITW 


or 


.WRITC area,chanum, bufadd,wrdcnt,cmprtn,blknum 


where: 

area is the address of a five-word argument block. 

chanum is a channel number in the range 0 to 17 (octal), previously defined in an 
open (.ENTER or .LOOKUP). 

bufadd is the address of the buffer containing the data to be written. 

wrdcnt is the number of words to be written. 

emprin is the address of a completion routine to which control is transferred when 
the write is complete. (For .WRITC only.) For .WRITE and .WRITW, control 
is returned to the instruction following the directive when the write is 
complete. 

blknum is the block number relative to the start of the file where the write is to 


begin. (For files opened with file-structured .ENTER or .LOOKUP.) For 
devices opened with non-file-structured .ENTER or .LOOKUP, the blknum 
argument is used as the absolute block number or device cluster number 
where the write is to begin. 


NOTE 


To access large files on RSTS/E systems, 
you must set the word at offset 2 in the 
scratch pad area (see Chapter 6). To do 
successive writes, your program must 
increment blknum. 


.WRITE/.WRITW/.WRITC 


Argument Block Format 


cc 


* The last word is set to 1 for .WRITE or to 0 for .WRITW. 


Errors 


Code Meaning 


0 No more room is available on the device. For example, the end-of-tape (EOT) 
marker has been encountered, no more available disk space, and so forth. 

1 Some hard I/O device error occurred. For example, the specified device is offline, 
is physically write-locked, and so forth. 

2 The channel specified is not open. 

Example 


The following code writes a 256-word block to the device open on channel 12: 


AREA: - BLKW 3) 
BUF: - BLKB S12. 


.WRITE #AREA, #12., #BUF, #256., #0 
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7.45. ..V1../..V2.. — Use Version 1/Version 2 Expansion 


If you have a source program that was coded for Version 1 or Version 2 of the RT- 
11 operating system and you want to assemble on RSTS/E using the expansions 
that were used for these versions, you must use either the ..V1.. directive (for 
Version 1 expansions) or the ..V2.. directive (for Version 2 expansions). 


You cannot use both the ..V1.. and ..V2.. directives. You can use directives 
from more than one version by specifying the ..V1.. directive and simply using 
the directives from later versions. If the same directive exists in two or three 
versions, though, you get the expansion from the earliest version. 


These directives generate code that defines and sets a variable called ...V1 to 
either 1 or 2, which the MACRO assembler uses to determine the expansions to 
use. So, if the .V1.. or ..V2.. directive is used, it must appear before any other 
RT-11 directives in your program. 


NOTE 


All the examples in this chapter show Version 2 expansions. Version 1 
expansions require different arguments in the calls. See RT-11 system 
documentation if you need to use version 1 expansions. 


Privileges Required 
None 


Macro Call 
VI1.. 
or 


V2. 
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Appendix A 


Full List of Errors 


This appendix lists the error messages that you may encounter when using 
RSTS/E. The question mark (?) and percent sign (%) characters preceding the full 


error text indicate the error’s severity: 


e A single question mark precedes nonfatal errors; the command failed but you 
can continue 


e A double question mark precedes severe errors; the command failed and you 
cannot continue 


e A percent sign precedes a warning message; the command may not have 
performed as you intended but execution continues 


Informational messages have neither character; they provide extra detail about 


the effects of a command. 


Table A—1 summarizes the RSTS/E error messages. 


Table A-1: 


ERR.STB 


Mnemonic 


BADDIR 
BADNAM 
INUSE 
NOROOM 
NOSUCH 
NODEVC 
NOTCLS 
NOTAVL 
NOTOPN 
PRVIOL 
HOF 
ABORT 
DATERR 
HNGDEV 
HNGTTY 


Decimal 
Value 


1 
2 
3 
A 
5 
6 
< 
8 
9 


RSTS/E Errors 


Octal 
Value 


Full Error Text 


??Bad directory for device 
?Tllegal file name 

?Account or device in use 
?No room for user on device 
?Can’t find file or account 
?Not a valid device 

?1/O channel already open 
?Device not available 

?V/O channel not open 
?Protection violation 

?End of file on device 
??Fatal system I/O failure 
?Data error on device 
?Device hung or write locked 
?Keyboard wait exhausted 


(continued on next page) 


Full List of Errors A-—1 


Table A-1 (Cont.): RSTS/E Errors 


ERR.STB Decimal Octal 


Mnemonic Value Value Full Error Text 

FIEXST 16 20 ?Name or account now exists 
DTOOOF 17 21 ?Too many open files on unit 
BADFUO 18 22 ?Illegal SYS () usage 
INTLCK 19 23 ?Disk block is interlocked 
WRGPAK 20 24 ?Pack IDs don’t match 
NOTMNT 21 25 ?Disk pack is not mounted 
PAKLCK 22 26 ?Device is restricted 
BADCLU 23 27 ?Tllegal cluster size 

PRIVAT 24 30 ?Account does not exist 
INTPAK 25 31 %Disk pack needs REBUILDing 
BADPAK 26 32 ??Disk pack mount error 
DETKEY 27 33 ?L/O to detached keyboard 
CTRLCE 28 34 Programmable “C trap 
SATTBD 29 35 ??Corrupted file structure 
DEVNES 30 36 ?Device not file-structured 
BADCNT 31 37 ?Illegal byte count for I/O 
NOBUFS 32 40 ?No buffer space available 
B.4 33 Al ??Odd address trap 

B.10 34 42 ??Reserved instruction trap 
B.250 35 43 ??Memory management trap 
B.STAK 36 44 ??SP stack overflow 

B.SWAP 37 A5 ??Disk error during swap 
B.PRTY 38 A6 ??Memory parity failure 
MAGSEL 39 47 ?Maptape select error 
MAGRLE 40 50 ?Maptape record length error 
NRRTS 41 51 ??Non-res run-time system 
VCSERR 42 52 ?Virtual buffer too large 
VCAERR 43 53 ?Virtual array not on disk 
SIZERR 44 54 ?Matrix or array too big 
VCOERR 45 55 ?Virtual array not yet open 
BSERR 46 56 ?Illegal YO channel 
LINERR A7 57 ?Line too long 

FLTERR 48 60 %¥Eloating point error 
EHXPERR 49 61 %Argument too large in EXP 
FMTERR 50 62 %Data format error 

FIXERR 51 63 %Integer error 

BDNERR 52 64 ?Tllegal number 

LOGERR 53 65 %{llegal argument 
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A-2 Full List of Errors 


Table A-1 (Cont.): RSTS/E Errors 


ERR.STB Decimal Octal 


Mnemonic Value Value Full Error Text 
SQRERR 54 66 %Imaginary square roots 
SUBERR 55 67 ?Subscript out of range 
MINVER 56 70 ?Can’t invert matrix 
ODD 57 71 ?Out of data 
ONBAD 58 72 ?7ON statement out of range 
NEDERR 59 713 ?Not enough data in record 
IOLERR 60 74, ?Integer overflow, FOR loop 
DIVBYO 61 75 %Division by 0 
NORTS 62 76 ?No run-time system 
FIELDE 63 77 ? FIELD overflows buffer 
NORACS 64 100 ?Not a random access device 
NOTMTA 65 101 ?Nlegal MAGTAPE() usage 
ERRERR 66 102 ?Missing special feature 
BADSWT 67 103 ?Illegal switch usage 
EOV 68 104 ?End of volume 
QUOTA 69 : 105 ?Quota exceeded 

70 106 ??Unused ERROR message 70 
STMERR 71 107 ?Statement not found 
HXITTM 72 110 ?7RETURN without GOSUB 
EXITNR 73 111 ?FNEND without function call 
UNDFNI 74 112 ?Undefined function called 
COSERR 75 113 ?Illegal symbol 
TLOPNV 76 114 ?Tllegal verb 
TLNZSP C7 115 ?legal expression 
TLNOIT 78 116 ?Tllegal mode mixing 
TLIFFE 79 117 ?Dlegal IF statement 
TLCONI 80 120 ?legal conditional clause 
TLNOTE 81 121 ?illegal function name 
TLQDUM 82 122 ?Tllegal dummy variable 
TLMFND 83 123 ?legal FN redefinition 
TLRNNM 84 124 ?Tlegal line number(s) 
MODERR 85 125 ?Modifier error 

86 126 ?Can’t compile statement 
OUTOAS 87 127 ?Expression too complicated 
FUNERR 88 130 ?Arguments don’t match 
TLTMAF 89 131 ?Too many arguments 
TLINCD 90 132 %Inconsistent function usage 
CPNSDF 91 133 ?Illegal DEF nesting 
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Full List of Errors A-3 


Table A-—1 (Cont.): RSTS/E Errors 


ERR.STB Decimal Octal 


Mnemonic Value Value Full Error Text 
CPUPFR 92 134 ?FOR without NEXT 
CPUFNX 93 135 ?NEXT without FOR 
CPUPDF 94. 136 ?DEF without FNEND 
CPUPED 95 137 ?FNEND without DEF 
TLJINKY 96 140 ?Literal string needed 
TLNOFN 97 141 ?Too few arguments 
SASYNE 98 142 ?Syntax error 
SAFNOS 99 143 ?String is needed 
SASNOI 100 144 ?Number is needed 
TLURTP 101 145 ?Data type error 
TLXDIM 102 146 ?1 or 2 dimensions only 
FUCORE 103 147 ??Program lost-sorry 
RESERR 104 150 ?7RESUME and no error 
DIMED2 105 151 ?Redimensioned array 
TLIDIM 106 152 %Inconsistent subscript use 
NOGOTO 107 153 ?7ON statement needs GOTO 
EOSERR 108 154 ?End of statement not seen 
TLCONTD 109 155 ?What? 
TLPRNM 110 156 ?Bad line number pair 
EDBMCE 111 157 ?Not enough available memory 
EDEXON 112 160 ?Execute only file 
NRNERR 113 161 ?Please use the RUN command 
EDCONE 114 162 ?Can’t CONTinue 
EDARSV 115 163 ?File exists-RENAME/REPLACE 
PRERRS 116 164 ?PRINT-USING format error 
UDMERR 117 165 ?Matrix or array without DIM 
PRNER1 118 166 ?Bad number in PRINT-USING 
NONOIM 119 167 ?Illegal in immediate mode 
PRNER2 120 170 ?PRINT-USING buffer overflow 
BADERR 121 171 ?TIllegal statement 
DISERR 122 172 ?Tilegal FIELD variable 
STPERR 123 173 Stop 
DIMERR 124 174 ?Matrix dimension error 
NOMATH 125 175 ?Wrong math package 
XCDCOR 126 176 ??Maximum memory exceeded 
SCAERR 127 177 %SCALE factor interlock 

128 200 ?Tape records not ANSI 

129 201 ?Tape BOT detected 
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A-—4 Full List of Errors 


Table A-—1 (Cont.): RSTS/E Errors 


ERR.STB Decimal Octal 


Mnemonic Value Value Full Error Text 
130 202 ?Key not changeable 
131 203 ?No current record 
132 204 ?Record has been deleted 
133 205 ?Illegal usage for device 
134 206 ?Duplicate key detected 
135 207 ?Tlegal usage 
136 210 ?Illegal or illogical access 
137 211 ?Illegal key attributes 
138 212 ?File is locked 
139 213 ?Invalid file options 
140 214 ?Index not initialized 
141 215 ?Illegal operation 
142 216 ?Illegal record on file 
143 217 ?Bad record identifier 
144 220 ?Invalid key of reference 
145 221 ?Key size too large 
146 222 ?Tape not ANSI labeled 
147 223 ?7RECORD number exceeds max 
148 224 ?Bad RECORDSIZE on OPEN 
149 225 ?Not at end of file 
150 226 ?No primary key specified 
151 227 ?Key field beyond record end 
152 230 ?Illogical record accessing 
153 231 ?Record already exists 
154 232 ?Record/bucket locked 
155 233 ?Record not found 
156 234 ?Size of record invalid 
157 235 ?Record on file too big 
158 236 ?Primary key out of sequence 
159 237 ?Key larger than record 
160 240 ?File attributes not matched 
161 241 ?Move overflows buffer 
162 242 ?Cannot open file 
163 243 ?No file name 
164 244 ?Terminal fmt file required 
165 245 ?Cannot position to HOF 
166 246 ?Negative fill or string len 
167 247 ?Illegal record format 
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Full List of Errors A-—5 


Table A-1 (Cont.): RSTS/E Errors 


i 
ERR.STB Decimal Octal 


Mnemonic Value Value Full Error Text 
a 
168 250 ?Tilegal ALLOW clause 
169 251 ??Unused ERROR message 169 
170 252 ?Indexed not fully optimized 
171 253 ?RRV not fully updated 
172 254 ?Record LOCK failed 
173 255 ?Invalid RFA field 
174. 256 ?Unexpired file date 
175 257 ?Node name error 
176 260 ?Negative TAB not allowed 
177 261 ?Too much data in record 
178 262 ?0PEN error - file corrupted 
179 263 ??Unused ERROR message 179 
180 264 ?No support for op in task 
181 265 ?Decimal overflow 
182 266 ?Network operation rejected 
183 267 ?REMAP overflows buffer 
184 270 ?Unaligned REMAP variable 
185 271 %RECORDSIZE overflows MAP 
186 272 ?Improper error handling 
187 273 ?INegal record lock clause 
188 274 ??Unused ERROR message 188 
189 275 ??Unused ERROR message 189 
190 276 ??Unused ERROR message 190 
191 277 ??Unused ERROR message 191 
192 300 ??Unused ERROR message 192 
193 301 ??Unused ERROR message 193 
194 302 ??Unused ERROR message 194 
195 303 ??Unused ERROR message 195 
196 304 ??Unused ERROR message 196 
197 305 ??Unused ERROR message 197 
198 306 ??Unused ERROR message 198 
199 307 ??Unused ERROR message 199 
200 310 ??Unused ERROR message 200 
201 311 ??Unused ERROR message 201 
202 312 ??Unused ERROR message 202 
203 313 ??Unused ERROR message 203 
204 314 ??Unused ERROR message 204 
205 315 ??Unused ERROR message 205 


a a ee eee 
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A-6 Full List of Errors 


Table A—1 (Cont.): 


ERR.STB 


Mnemonic 


Decimal 
Value 


206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 
224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
240 
241 
242 
243 


RSTS/E Errors 


Octal 
Value 


316 
317 
320 
321 
322 
323 
324 
325 
326 
327 
330 
331 
332 
333 
334 
335 
336 
337 
340 
341 
342 
343 
344 
345 
346 
347 
350 
351 
352 
353 
354 
355 
356 
357 
360 
361 
362 
363 


* Full Error Text 


??U0nused ERROR message 206 
??Unused ERROR message 207 
??Unused ERROR message 208 
??Unused ERROR message 209 
??Unused ERROR message 210 
??0Unused ERROR message 211 
??Unused ERROR message 212 
??Unused ERROR message 213 
??Unused ERROR message 214 
??Unused ERROR message 215 
??Unused ERROR message 216 
??Unused ERROR message 217 
??Unused ERROR message 218 
??Unused ERROR message 219 
??Unused ERROR message 220 
??Unused ERROR message 221 
??Unused ERROR message 222 
??Unused ERROR message 223 
??Unused ERROR message 224 
??Unused ERROR message 225 
??0nused ERROR message 226 
?String too long 
?7RECORDTYPES not matched 
??Unused ERROR message 229 
?No fields in image 

?Illegal string image 

?Null image 

?Tlegal numeric image 
?Numeric image for string 
?String image for numeric 
?TIME limit exceeded 

?1st arg to SEQ$ > 2nd 
?Arrays must be same DIM 
?Arrays must be square 
?Cannot change array DIMs 
?Floating overflow 

?Floating underflow 

?CHAIN to nonexistent line 
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Full List of Errors 


A-7 


Table A-—1 (Cont.): RSTS/E Errors 


ERR.STB Decimal Octal 


Mnemonic Value Value Full Error Text 
244 364 ?Exponentiation error 
245 365 ?Ilegal exit from DEF* 
246 366 ?Error trap needs RESUME 
247 367 ?Tllegal RESUME to SUBR 
248 370 ?Illegal subroutine return 
249 371 ?Argument out of bounds 
250 372 ?Not implemented 
251 373 ?Recursive subroutine call 
252 374 ?FILE ACP failure 
253 375 ?Directive error 
254 376 ??Unused ERROR message 254 
255 377 ??Unused ERROR message 255 
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Appendix B 


Device Information 


This appendix summarizes MODE and RECORD values and other useful 
information for: 


e Disks 

e Flexible diskettes 
e Magnetic tape 

e Line printers 

e Terminals 


¢ Pseudo keyboards 


For your convenience, the tables show both decimal and octal values, and list the 
FIRQB and XRB offsets. All decimal values have a decimal point; values without 
a decimal point are in octal. 


This appendix is a quick reference. See the RSTS/E Programming Manual 
(except where otherwise noted) if you need more detail on any topic. 


B.1 Disks 


This section summarizes disk MODE values and lists the device cluster size and 
total size for each disk that RSTS/E supports. 


Table B—1 summarizes disk MODE values for file-structured access. 


Table B—1: MODE Values for File-Structured Disk Access (FIRQB+FQMODE) 


Decimal Octal Function 

0. 0 Normal read/write 

l. 1 Update 

2. 2 Append 

4. 4 Guarded update (4 + 1) 

8. LO Special extend (RSTS/E updates file’s size and retrieval pointers 
during extend operations) 

16. 20 Create contiguous file 

32. 40 Create tentative file 
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Device Information B—1 


Table B—1 (Cont.): MODE Values for File-Structured Disk Access (FIRQB+FQMODE) 


Decimal Octal Function 


64 100 Create contiguous file conditionally 

128 200 No supersede 

256. 400 Random data caching (requires TUNE privilege) 

512. 1000 Create file and place at beginning of directory (with 2000) 
1024. 2000 Create file and place at end of directory 

2048. 4000 Sequential data caching (with 400) 

4096. 10000 Read normally regardless 

8192. 20000 Open file read-only 

16384. 40000 Write UFD (requires WRTNFS privilege) 


_ OO eee eee 


Table B—2 summarizes disk MODE values for non-file-structured access. 


Table B-2: MODE Values for Non-File-Structured Disk Access (FIRQB+FQMODE) 


Decimal Octal Function 


0. 0 Access device clusters. 
128. 200 Access disk blocks. 
512. 1000 Read beyond last writable portion of disk; suppress error logging. 


(Reserved for use by Digital.) 


Table B-3 lists the device cluster size and device size (in 512-byte blocks) for each 
disk that RSTS/E supports. All values are decimal. 


Table B-3: Disk Device Sizes 


Minimum Device 


Disk Cluster Size Device Size 

RX50 1 800 

RKO5 1 4800 

RKO5F 1 4800 per unit; 2 units for each drive 
RLO1 1 10,220 

RLO2 1 20,460 

RD51 1 21,600 

RK06 1 27,104 

RKO7 1 53,768 

RD52 1 60,479 

RC25 1 50,902 per unit; 2 units per spindle 
RMO02 4 131,648 

RM03 4 131,648 

RD53 4 138,668 

RP04 4 171,796 


(continued on next page) 


B-2 Device Information 


Table B-3 (Cont.): Disk Device Sizes 


Minimum Device 


Disk Cluster Size Device Size 
RP0O5 4 171,796 
RA80 4 237,208 
RM80 4 242,575 
RD54 8 311,200 
RP0O6 8 340,664 
RA60 8 400,175 
RM0O5 8 500,352 
RA70 16 547,040 
RA81 16 888,012 
RA82 32 1,216,640 
RA90 64 2,376,128 


B.2 Flexible Diskettes 


This section summarizes MODE and RECORD values for RX01 and RX02 flexible 
diskettes. Table B—4 lists MODE values for flexible diskettes. 


Table B-4: Flexible Diskette MODE Values (FIRQB+FQMODE) 


Decimal Octal Function 
0. 0 Block mode 
16384. 40000 Sector mode 


Table B—5 lists RECORD values for flexible diskettes. 


Table B-5: Flexible Diskette RECORD Values (XRB+XRBLK) 


Decimal Octal Function 

8192. 20000 Access logical record 0 

16384. 40000 Write deleted data mark 

32767.+1. 100000 Perform this I/O operation in block mode 


Device Information B-3 


B.3 Magnetic Tape 


This section summarizes MODE and CLUSTERSIZE values for magnetic tape. 
Table B-6 lists MODE values for file-structured magnetic tape. 


Table B-6: MODE Values for File-Structured Magnetic Tape (FIRQB+FQMODE) 


Decimal Octal Function 

0. 0 Read file label at current tape position 

2. 2 Do not rewind tape when searching for file 

16. 20 Write over existing file 

32. 40 Rewind tape before searching for file 

64, 100 Rewind on CLOSE 

128. 200 Open for append 

512. 1000 Write new file label without searching 

1024. 2000 Use block length field as specified in /FILESIZE in place of 


record length field in /CLUSTERSIZE. Only meaningful on 
ANSI tape, when the record length field is zero. 


16384. 40000 Search for DOS-formatted file label 
24576. 60000 Search for ANSI-formatted file label 


Table B—7 lists CLUSTERSIZE values for file-structured magnetic tape. The 
value in FIRQB+FQCLUS is the sum of the values chosen from Table B—7. The 
default value is zero. : 


NOTE 


The CLUSTERSIZE option is only effective when processing ANSI- 
formatted magnetic tape. 


Table B-7: CLUSTERSIZE Values for File-Structured Magnetic Tape Files 
(FIRQB+FQCLUS) 


Label Field 

Name Decimal Octal Label Result 

Record format 0. 0 U = undefined. Tf 
16384. 40000 F = fixed-length. 
32767.+1. ~ 100000 D = variable length. 
-16384. 140000 S = spanned. f£ 

Record length (in Between 0. Between 0 For U, always 0. 

bytes) and 4095. and 7777 For F, fixed record length. 


For D, maximum record length. 

For S, not used. £ 

If this value is 0% and mode 1024% 
is used, then the record length field 
is set equal to the block length 
value specified in /FILESIZE=. 


tRSTS/E undefined record formats cannot be processed directly by most of the other operating 
systems. 


tRSTS/E does not support ANSI format S records. 
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B—4 Device Information 


Table B-7 (Cont.): CLUSTERSIZE Values for File-Structured Magnetic Tape 
Files (FIRQB+FQCLUS) 


Label Field 
Name Decimal Octal Label Result 
System 0. 0 M = carriage control embedded. 
Dependent (File 
characteristics) 
4096. 10000 A = FORTRAN carriage control. 
8192. 20000 (space) = implied carriage control. 


When printed, line feed precedes 
and carriage return follows each 
record. 


MODE values in non-file-structured magnetic tape processing have the form: 
MODE(FIRQB+FQMODE) =D+P+S8 


where: 
D (density) = 12.(14) for 800 bpi 
256.(400) for 1600 bpi, phase-encoded 
P (parity) = 0.(0) for odd 
1.(1) for even (800 bpi only) 
S (stay) = 0.(0) to clear MODE value after CLOSE 


8192.(20000) to retain MODE value after CLOSE 


Note that Digital recommends the use of odd parity. When you use even parity, 
you cannot write binary data. In addition, many operating systems and tape 
drives do not support even parity. 


For information on magnetic tape special functions, the magnetic tape status 
word, and the file characteristics word, see the description of .SPEC for magnetic 
tape (see Chapter 3). 
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B.4 Line Printers 


This section summarizes line printer MODE and RECORD values. Table B—8 
lists the MODE values for line printers. 


Table B-8: Line Printer MODE Values (FIRQB+FQMODE) 


Decimal Octal Function 


1. to127. 1to177 Sets form length to number of lines per page for software 
formatting (512., 1000) and automatic page skip (2048., 4000). 


128. 200 Changes the character 0 (zero) to O (letter "oh"). 

256. 400 Truncates lines that are longer than unit was configured for 
instead of printing the rest of the line on the next physical line 
on the page. 

512. 1000 Enables software formatting. Forms control characters are > 
200(8). 

1024. 2000 Translates lowercase characters to uppercase characters. Applies 
only to uppercase and lowercase line printers. 

2048. 4000 Skips six lines (that is, skips over perforation line) at the bottom 
of each form. 

4096. 10000 Moves paper to top of hardware form. 

8192. 20000 Suppresses form feed on CLOSE. 


Table B—9 lists the RECORD values for line printers. 


Table B-9: Line Printer RECORD Values (XRB+XRMOD) 


Decimal Octal Function 

2. 2 Print over perforation (disables MODE 4000 for this output 
step). 

4, 4 Do not return control to program until output is complete or an 
error occurs. 

8. 10 Clear pending output buffers before buffering characters for the 
request. 

8192. 20000 Return control to program if output stall is to occur. (See the 


WRITE directive for more information. ) 
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B.5 Terminals 


This section summarizes MODE and RECORD values for terminals. It also 
includes information about echo control mode and VT100 ANSI-compatible escape 
sequences. 


Table B—10 lists MODE values for terminal input. 


Table B—10: Terminal MODE Values (FIRQB+FQMODE) 


Decimal Octal Function 

1. 1 Enable binary input from a terminal 

2 2 Reserved for TECO 

4, 4 Suppress automatic CR/LF at right margin 

8 10 Enable echo control (turns off other modes and automatically 
enables MODE 4) 

16. 20 Guard program against Ctrl/C interruption and dial-up line 
hibernation 

32. 40 Enable incoming XON/XOFF processing 

64. 100 Reserved 

128. 200 Enable use of RUBOUT as a delimiter on video terminals 

256. 400 Set escape sequence mode 

16384. 40000 Transparent control character mode 


Table B—11 lists RECORD values for terminal input. 


Table B—11: RECORD Values for Terminal Input (XRB+XRMOD) 


Decimal Octal Function 

256. 400 Force interactive read (always obtain data from the 
user’s terminal, never from a command file) 

8192. 20000 Perform conditional input (execute input request 
without waiting for data to be available). 

32767.41.4K 100000+K Perform multiterminal service input from assigned 
keyboard number K. 

32767.4+1.+ 140000+S Perform multiterminal service input from any as- 

16384.+5 signed keyboard: 
S=0 Wait until input is available from 


any terminal. The error ?Data 
error on device may occur due to a 
race condition with Ctrl/C. 


1. < 5S < 255. Wait up to S seconds for input 


1<S < 377 from any terminal and then return 
?Data error on device if no input is 
available. 

S = 8192. Request input immediately; return 

S = 20000 ?Data error on device if no input is 
pending. 
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Table B—12 lists RECORD values for terminal output. 


Table B-12: RECORD Values for Terminal Output (XRB+XRMOD) 


Decimal Octal Function 

256. 400 Declare echo control field (use with MODE 10). 

4096. 10000 Output binary data to terminal. 

8192. 20000 Return control to program if output stall is to occur. 
(See the .WRITE directive for more information.) 

16384. 40000 Transparent control character mode. 

32767.4+1.4K 100000+K Perform multiterminal service output to assigned 
keyboard K. 


In echo control mode, the system strips the parity bit from all characters. All 
characters returned to your program have ASCII values in the range 1 to 255. 
The system does not pass synchronization or editing characters to your program. 
Delimiters are passed to your program but are never echoed. Table B—13 lists the 
echo control mode character set. 


Table B-13: Echo Control Mode Character Set 


Code 
Type of ASCII Code Returned 
Character (Octal) to User Comments 
Ignored 0 Used as filler for timing 
Delimiters Private ? Private delimiter. 
3 3 AC (Ctrl/C). 
4 4 AD (Ctrl/D). 
12 12 Line feed. 
14 14 Form feed. 
15 15,12 Carriage return (with line feed 
appended). 
32 32 AZ (Ctrl/Z),; generates error 11(10). 
33 33 If the Escape_Sequence charac- 
teristic is not in effect and escape 
character is received, 33 is re- 
turned to user and is treated 
as a delimiter. If the Escape_ 
Sequence characteristic is in ef- 
fect, escape character triggers an 
escape sequence. The escape se- 
quence is returned to user and the 
whole sequence is considered the 
delimiter. 
175 33 or 175 If the Alt_Mode characteristic is in 


effect, 175 is translated to escape 
(33). If the Alt_Mode characteristic 
is not in effect, 175 is data. 


(continued on next page) 
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Table B-13 (Cont.): 


Type of 
Character 


Editing 


Data 


Synchro- niza- 
tion 


Other 


ASCII Code 


(Octal) 


176 


L177 


25 


40-137 
241-337 


140-176 
340-376 


140-176 
340-376 


21 


23 


1,2,5,6 
7,10,11, 
13,16-20, 
22,24, 
26-31, 
34-37 


21,23 


Code 


Returned 


to User 


33 or 176 


40-137 
241-337 


100-136 
300-336 


140-176 
340-376 


Echo Control Mode Character Set 


Comments 


If the Alt_ Mode characteristic is in 
effect, 176 is translated to escape 
(33). If the Alt_ Mode characteristic 
is not in effect, 176 is data. 


RUBOUT (DEL character); on video 
terminals, generates a backspace 
followed by the paint character 

and another backspace; on hard- 
copy terminals, echoes deleted 
characters between backslashes 


(\\). 


AU (Ctrl/U); repeatedly simulates 
RUBOUT until no characters 
remain in field. 


Normal 64-character graphic set. 


If the Lowercase=input characteris- 
tic is not set, lowercase letters are 
translated to uppercase. 


If the Lowercase=input character- 
istic is set, lowercase letters are 
returned to user. 

XON (Ctrl/Q). Resume suspended 
output (if the TT Sync characteristic 
is set). 


XOFF (Ctrl/S). Suspend output (if 
the TTSync characteristic is set). 


Echoed as BEL (7) but otherwise 
ignored. 


If the terminal is set No TTSync, 
synchronization characters are also 
echoed as BEL (7) and ignored. 
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Use .WRITE to declare a field. The .WRITE must include the value 400 at 
XRB+XRMOD and the value N at XRB+XRBC. N, which must be between 1 and 
the size of the buffer, describes how many bytes in the buffer represent the field 
declaration: 


N=1 The byte contains field size and overflow handling information. The field size 
must be in the range 1 to 177. Adding 200 to the field size specifies keypunch 
overflow handling instead of normal overflow handling. 


N = 2 The first byte contains field size and overflow handling as described for N = 1. 
The second byte contains the ASCII value of the paint character. If this byte is 
0 or N = 1, a space is the paint character. 


N > 2 The first (N-2) bytes contain a prompt to display on the terminal before the 
field. Byte (N-1) is the field size declaration as described for N = 1. The last 
byte is the paint character as described for N = 2. 


B.6 Pseudo Keyboards 


This section summarizes MODE and RECORD values for pseudo keyboards. It 
also lists errors your program can receive on a pseudo keyboard output request. 


Table B—14 lists MODE values for pseudo keyboards. 


Table B-14: Pseudo Keyboard MODE Values (FIRQB+FQMODE) 


Decimal Octal Function 

0. 0 System kills controlled job when the pseudo keyboard is closed 

1. 1 System detaches controlled job when the pseudo keyboard is 
closed 


Table B—15 lists RECORD values for pseudo keyboards. 


Table B-15: RECORD Option Bit Values for Pseudo Keyboard Output 


(XRB+XRMOD) 
Bit Decimal Octal Result 
0 is 1 If set, the system does not check job status before sending 
data to the pseudo keyboard. 
1 2. 2 If set, the system tests whether pseudo keyboard is 


waiting for a system command (Ctr//C state) or is waiting 
for program input (KB wait state). 


2 4, 4 If set, the system does not send data to the pseudo 
keyboard but instead returns control to the controlling 
job. 

3 8. 10 If set, and there are no small buffers for keyboard 


input, the system waits until small buffers are available. 
However, your program receives the NOROOM error if 
the output buffer chain is full. 


4 16. 20 If set, the system kills the job currently running at the 
pseudo keyboard. 
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Table B—16 lists errors that your program can receive on a pseudo keyboard 
output request. 


Table B-16: Possible Errors on Pseudo Keyboard Output Request 


Error Meaning 

INUSE Job at pseudo keyboard is not ready for input 
NOROOM_ No buffer space is available 

NOSUCH No controlled job exists at pseudo keyboard 
CTRLCE Job at pseudo keyboard is not in Ctrl/C state 
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Index 


A 


Abbreviation point (CCL), 3-64 
ABRT$, 5-4 
Account 

creating, 3-348 

deleting, 3—307 

reading data for, 3-358 

resetting data for, 3-358 
Accounting information dump, 3-251 
Account number 

!, 3-83 

#, 3-83 

$, 3-83 

%, 3-83 

&, 3-83 

@, 3-83, 3-238 

file specification, 3-83 

wildcard, 3-84 
Active Page Register 


See APR 
Addressing, 2—1, 2-2 
Allocating a device, 3-13 
ALUN$, 5-5 
AME (Application Migration Executive), RSX emulator, 
4—1 
ANALYS program, 3-351 
ANS! magnetic tape 
CLUSTERSIZE values, B—4 
Application Migration Executive 


See AME 
APR (Active Page Register), 2-1, 2-2, 2-5, 2-20, 
2-21 
kernel mode, 2—4, 3-137 
used to map windows, 3-144 
user mode, 2-4 
Argument block, RT-11 directives, 6—5 
Assembler, 1-3 
ASSFQ, 3-13 to 3-15 
Assign LAT port, 3-117 
AST, 3-10 
AST (Asynchronous Trap), 2-16, 5-54 
ASTX$, 5-6 
Asynchronous exception, 5-6, 5-54 
handler, 2-23 
Asynchronous Trap 


See AST 
ATRFQ, 3-140 to 3-143 
ATRG$, 5-8 
Attach to job, 3-262 
Attribute, 3-254, 3-317 


B 


B.10, kernel mode vector, 2-22 
B.250, kernel mode vector, 2-22 
B.4, kernel mode vector, 2-22 
B.PRTY, 2-25 
B.STAK, 2-25 
B.SWAP, 2-25 
Back spacing magnetic tape, 3-209 
BASIC-PLUS 

run-time system, 1—1, 2-5, 2-21 

SYS calls, 3-248 to 3-413 
Binary file 

creating, 3-18 

opening, 3-18 
Binary mode, 3-219 
.BLKBO, 3—5 
.BLKWO, 3-5 
BLOCK option, 3-167, 3-172, 3-416, 3-421 
Block-random devices, 3—165 
Block-sequential devices, 3-165 
BPT instruction, 2-16 
Broadcast to terminal, 3-216 
SECT, 3-5 
Buffering, disabling full line, 3-230 
Buffer size 

reads, 3-165, 3-166 

writes, 3-419 
Byte-oriented devices, 3-165 


C 


Caching 
disabling disk, 3-282 
enabling disk, 3—282 
CALFIP, 3-12 to 3-63 
summary of subfunctions, 3-12 
CALL, 3-5 
Call formats, RT-11 directives, 6—5 
CALLR, 3-6 
CALLRX, 3-6 
CALLX, 3-6 
Card reader 
reads, 3-165 
Carry bit, 7-58 
CCL command, 3-64 
adding, 3-269 
deleting, 3-269 
/DETACH switch, 3-65 
getting command line, 5-33 
RT-11 .DOCCL, 7-23 
/SIZE switch, 3-65 
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CCL command (Cont.) 
string passed in CORCMN, 2-15 
.CCL directive, 2-15, 3-64 to 3-67 
/DETACH switch, 2-28 
/SIZE switch, 2-28 
CCLLST, 3-397 


.CHAIN, 3-68 
RT-11, 7-6 to 7-7 
Channel 


checking for open, 7-63 
closing, 3-16, 7-38 
closing under RT-11, 7-8, 7-57 
releasing, 7-42 
reset, 3-61 
Channel number, 3-7 
under RT-11, 6-7 
Circuit counters, 3-195, 3-197 
.CLEAR, 3-69 to 3-70 
.CLEAR directive, 2-10 
.CLOSE, 7-8 
CLOSE, negative channel number (reset), 3-61 
Close flag, 3-300 
Closing a channel, 3-16 
.CLRFQB, 7-9 
CLRFQB routine, 3-7 
CLRFQOX routine, 3-7 
.CLRXRB, 7-10 
CLRXRB routine, 3-7 
CLSFQ, 3-16 to 3-17 
CLUSTERSIZE option, 3-25, 3-32, 3-55 
ANSI magnetic tape, B—4 
/CLUSTERSIZE switch, 3-81, 7-11 
CLUSTR offset, 6-12 
.CMDLN, 3-71 to 3-72 
Command, CCL, 3-64 
COMMON.MAC, 2-9, 3-2 to 3-6, 3-248, 6-3 
how to assemble with, 3-3 
macros provided with, 3-3 
mnemonics assigned to FIRQB, 2-12 
mnemonics for pseudovectors, 2-16 
Concise Command Language 


See CCL 
Context, job, 2-11 
Control characters, vertical format, 5—49t 
Conversion, date and time, 3-295 
CORCMN 
definition, 2-14 
format, 2—-15f 
low 512 bytes, 2-9f 
.CORE, 3-76 
Core common, definition, 2-14 
.CORE directive, 2-11, 2-21 
CRAFQ, 3-144 to 3-148 
CRASH.SYS, DUMP/SYSTEM command, 3-351 


CRAWS, 5-11 
CRBFQ, 3-18 to 3-22 
Create 
binary file, 3-18 
file, 3-23 


logged-in job to enter keyboard monitor, 3-323 
logged-in job to run program, 3-821 
logged-out job, 3-320 
temporary file, 3-30 

Create LAT port, 3-113 

CREFQ, 3-23 to 3-29 

CRMSBS offset, 6-12 

CRRG§$, 5-16 
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CRTFQ, 3-30 to 3-33 

.CSIGEN, 7-11 to 7-14 

.CSISPC, 7-15 to 7-17 

CSRTBL, 3-397 

Ctri/C, 2-16, 2-24 
asynchronous exception, 5-54 
processing, 7-51 
restarting output stopped by, 3-233 
stopping action of, 6-12 

Ctrl/O 
canceling, 3-216 
effect, 2-24 
restarting output stopped by, 3-233 
reversing, 7—43 

Ctrl/Z, 7-49 


D 


DALFQ, 3-34 
Data caching 
See Caching 
Dataset, hanging up, 3-319 
Data Space (D-Space), 2-5 
Date 
changing system, 3-298 
conversion, 3—295 
current, 5-36 
returning under RT-11, 7—20 
return to RO, 7-18 
DATE, 3-77 to 3-78 
RT-11, 7-18 to 7-19 
.DATTIM, 7-20, 7-21 
DCL (Digital Command Language) 
run-time system, 1—1 
DCL run-time system, 2-26 
DDB (Device Data Block), 3-311 
DDCTBL, 3-399 
DDNFS, 3-27, 3-56, 3-95 
DDRLO, 3-27, 3-56, 3-95 
DDWLO, 3~27, 3-56, 3-95 
DEAFQ, 3-35 to 3-36 
Deallocate 
all devices, 3-34 
device, 3-35 
Deassign LAT port, 3-120 
Declare receiver, 3-100 
DECnev/E, 3-100 
DECtape 
deleting file from, 3-42 
get directory for, 3-37 
reads, 3-165, 3-166 
rename file, 3-59 
writing data, 3-419 
Default keyboard monitor, 2-25, 3-80, 3-178, 7-31 
See also Primary run-time system 
Default runnable file type, 2-20 
Default system keyboard monitor, 3-179 
DEFORG, 3-3 
DELETE, 7-22 
Delete LAT port, 3-115 
Deleting 
account, 3-307 
file, 3-42 
Delimiters 
line, 3-165 
multiple private, 3-218 to 3-224 
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private, 3-218 
Density, setting magnetic tape, 3-209 
Detach 
resident library, 3-149 
Detached job quota, 3-268 
Detaching job, 3-300 
/DETACH switch, in CCL command, 3—65 
DEVCLU, 3-399 
DEVCNT, 3-895 
Device 
allocating, 3-13, 3-234, 3-252 
block-random, 3-166, 3-419 
block-sequential, 3-165, 3-419 
byte-oriented, 3-165, 3-419 
checking availability, 7-32 
deallocating, 3-35, 3-234, 3-245, 3-299 
deallocating all, 3-34, 3-243, 3-297 
disk sizes, B—2 
handler index, 3-96 
logical name, 3-82, 3-92 
open (non-file-structured), 3-53 
physical name, 3-82 
reading, 3-165 
reallocating, 3-234, 3-252 
record-oriented, 5-48 
return status, 7-26 
seize operation, 3-237 
writing data to, 3-414, 3-419 
zeroing, 3-411 
Device block, 6-7, 6-8 
creating, 7-15 
Device Data Block 
See DDB 
Device handler index, 3-28, 3-57 
Device-type flags, 3-27, 3-56, 3-95 
DEVNAM, 3-397 
DEVOKB, 3-397 
DEVPTR, 3-395 
DEVSYN, 3-397 
DIC (Directive Identification Code), 4-3 
byte, DPB, 4—5 
DIGITAL Command Language 
See DCL 
DIR$, 4-4 
general form, 4-5 
other features, 4—6 
Directive 
expansions for RSX, 4-2 
expansions for RT-11, 6—4 
monitor, 1—4 
RSX, 1-4 
RT-11, 1-4 
Directive Identification Code 
See DIC 
Directive Parameter Block 
See DPB 
Directives 
emulator, 1—4 
Directive Status Word 
See DSW 
Directory 
get information, 3-37 
lookup, 3-38 
lookup by file name, 3-334 
lookup on index, 3-303 
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magnetic tape lookup, 3-305, 3-306 
privileged and nonprivileged access, 3-37 
wildcard lookup, 3-336 
DIRFQ, 3-37 to 3-41 
Disable terminal, 3—290 
Disk 
changing logical name of, 3-375 
changing quota, 3-290 
deleting file from, 3-42 
device cluster sizes, B-2 
device sizes, B-2 
directory lookup by file name, 3-334 
dirty bit, 3-341 
disabling caching, 3-282 
enabling caching, 3-282 
file lookup by name, 3—46 
get directory for, 3-37 
locking blocks, 3-190 
MODE values, B—1 
mounting, 3-338 
reads, 3-166 
rename file, 3-59 
swapping to, 3-69, 3-186 
wildcard directory lookup, 3-336 
writing data, 3-419 
Disk quota, 3-268 
DLNFQ, 3—42 to 3-43 
DMC11/DMR11 
number of receive buffers, 3-54, 3-55 
reads, 3-165 
receive buffer size, 3—54 
writing data, 3-419 
.DOCCL, 7-23 
.DOFSS, 7-24 
.DORUN, 7-25 
$DPB$$, 4-7 
DPB (Directive Parameter Block), 4-3 
$C form, 4-6 
DIC byte, 4-5 
$form, 4-4 
general form, 4-3 
$S form, 4-7 
.DSECT, 3-4 
DSKLOG, 3-397 
.DSTATUS, 7-26, 7-27 
DSTPTR, 3-399 
DSW (Directive Status Word) 
return codes, 4-3 
$DSW mnemonic 
DSW (Directive Status Word), 4-3 
DTRFQ, 3-149 to 3-150 
DTRG$, 5-18 
Dump, snap shot, 3-308, 3-351 
DUMP/SYSTEM command, CRASH.SYS, 3-351 
Dynamic region, creating, 3-362, 3-370, 5-16 
Dynamic region, I/O, 3-165, 3-170 
Dynamic region, limit, 3-277 


E 


Echo 
disabling, 3-214, 3-216 
enabling, 3-214, 3-216 
stopping, 3-232 

Echo control mode 
character set, B—8t 


Index—3 


Echo control mode (Cont.) E 
declaring a field, B—10 


ELAFQ, 3—151 to 3-153 Fast-mapping, 3-70, 3-186 
ELAW$, 5-20 Fast-mapping facility, 3-159 to 3-160, 542 to 5-43 
EMT, 2—4f FCB (File Control Block), 3-311 

instruction, 2-18, 2-23, 6-4 FCBLST, 3-397 

special prefix, 1-4, 2-19, 2-23, 6-3 FEA (Floating-point Error Address), 2-23, 5-6, 7-54 
EMT 377, 4-3 FEADF$, 5-29 
EMT logging, 3-101, 3-109 FEAT$, 5-30 . 
Emulator, 1-2 FEC (Floating-point Exception Code), 2-23, 5-6, 7-54 

directives, 1-4 ‘FETCH, 7-32 

RSX directives, 5—1 File . 

RT-11 directives, 7-1 to 7-66 adding system, 3-383 

trap, 2-18 associating with run-time system, 3-342 
End-of-file (EOF), magnetic tape, 3-209 changing statistics, 3-266 
.ENTER, 7-28 creating, 3-23 
Entry points, 2-25 creating binary, 3-18 
.EQUATE, 3-5 creating temporary, 3-30 
ERLCTL, 3-397 deleting, 3-42 
.ERLOG, 3-79 deleting from DECtape, 7-22 
ERR.STB deleting from disk, 7-22 

symbol table file, 3-6 listing system, 3-383, 3-386 
ERRFQ, 3-44 to 3-45 lookup by name (disk), 3-46 
Error log, 2-20 open existing, 3-53, 7-39 
Error message open for input, 3-53, 7-39 

printing text, 7-30 open for output, 7-28 

returning text, 3-44, 3-309 opening binary, 3-18 

RSTS/E set, A-1 to A-8 ; opening file-structured, 3-23 
Error mnemonics, 3-6, A-1 to A-8 opening temporary, 3-30 
Errors placement and modification, 3-315 

logging, 3-79 processor, 3-248 

pseudo keyboard output request, B—11 read attributes, 3-254 
.ERRPRT, 7-30 reading, 3-165 
Escape sequences, 3-218 read under RT-11, 7-44 

mode, 3-219 removing system, 3-383, 3-384 
Ethernet, 3-193 renaming, 3-59, 7—46 

circuit counters, 3-195, 3-197 reopen, lees 

line counters, 3-196, 3-199 returning attribute, 3-317 

multicast addresses, 3-194 saving status of, 7-48 

physical address, 3-193 specification, 3-82, 7-24 
Exception spooling, 3-379 

asynchronous, 2-23 tentative, 3-61 

synchronous, 2-21, 5-58, 5-60 wildcard lookup, 3-46 
.EXIT, 3-80 write attributes, 3-254 

RT-11, 7-31 writing data to, 3-414, 3-419 
EXIT$, 5-22 File access 
Expand checking, 3-284 

memory allocation, 3-73 File characteristics word, magnetic tape, 3-212 

memory size, 2-11 File Control Block 
Expiration date, changing, 3-290 . See FCB 
EXQTA privilege, 2-11 File name 
EXST$, 5-23 file specification, 3-84 
Extended Buffer Pool string scan, 2-15 

See XBUF File name string scan, 3-8, 3-81 
Extended logical area of job header, 2—15, 3-85, _ under RT-11, 7-24 

3-235 File Processor 

.FSS causes check of, 3-82 . See FIP 
Extended-memory calls (RT-11), 6-1 File request queue block, 2-12 
Extended Record Block FILESIZE option, 3-24 

See XAB /FILESIZE switch, 3-81, 7-11 
Extend memory allocation, 3-73 File specification, 3-81 
Extend task by mask, 5-26 order of elements, 3-84 
EXTK$, 3-75, 5-24 File-structured, open, 3-23 
EXTM$ Directive, 5-26 File type 


default runnable, 2-20 
file specification, 3-84 
FIP (File Processor), 3-63, 3-248 
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FIP (File Processor) (Cont.) 


GMCR$, 5-33 
calls, 3-63 GPRT$, 5-34 
FIRQB .GTIM, 7-34 
clearing under RT-11, 7—9 GTIM$, 5-36 
data returned to, 3-7 GTUB, 7-35 
definition, 2-12 .GTLIN, 7-36 
general format, 2—13f GTSK$, 3-75, 5-38 
low 512 bytes, 2-9f GVAL directive, 7-37 
mnemonics assigned to, 2-12 
P.RUN entry, 2-28 H 
presetting to zero, 3-6 
routine to clear, 3-7 Handler index, device, 3-28, 3-57, 3-96, 7-26 
setting up under RT-11, 7-52 Hanging up a dataset, 3-319 
size of, 2-12 High segment, 2-5, 2-8f, 2-16 to 2-30 
translating string to, 3-81 Horizontal position, 3-163 
Fixed monitor locations, 3—137t HRESET, 7-38 
Flag 
close, 3-300 
device-type, 3-27, 3-56, 3-95 
Flag word 1 (.FSS), 3-88 l&D Space (Instruction and Data Space), 1-4, 2-5, 
Flag word 2 (.FSS), 3-86 5-24 
Flexible diskette memory management, 2-2 
changing density, 3-204 VO 
MODE values, B-3 general directives for, 3-8 
obtaining density, 3-204 non-file-structured, 5-47 
reads, 3-166 page, o—Af 
RECORD option, B-3 RSX emulation environment, 5—47 
special functions for, 3-204 special functions for, 3-189 
writing data, 3-419 special functions under RT-11, 7-55 
FLGFRC, 3-27, 3—56, 3-95 synchronous, 5-47 
FLGKB, 3-27, 3-56, 3-95 /O Status Buffer (ISB), 5—49 
FLGMOD, 3-27, 3-56, 3-95 IDENT, 3-3 
FLGPOS, 3-27, 3-56, 3-95 INCLUDE, 3—4 
FLGRND, 3-27, 3-56, 3-95 Infinite-wait read, 2-26, 3-168 
Floating-point INIT, 2-5 
errors, 7—54 INSTALL/RUNTIME_SYSTEM command, 2-18 
processor, 2-16 Instruction and Data Space 


processor exception address, 5-55 

processor exceptions, 5-6 

unit, 2-11, 2-23, 3-186, 7-54 
Floating-point Error Address 


See I&D Space 
Instruction Space (I-Space), 2-5 


See FEA J 
Floating-point Exception Code JBSTAT, 3-395 

See FEC JBWAIT, 3-395 
Force to keyboard, 3-216 JDFSTM, 3-69, 3-70, 3-186 
Foreground/background, 6—1 JFBIG, 3-69, 3-186 
FORTRAN, resident library access directives, 4—8 bit in KEY, 2-11 
FREES, 3-397 JFFPP, 3-69, 3-70, 3-186 
.FSS, 3-81 to 3-91 bit in KEY, 2-11 

/O support, 3-8 JFLOCK, 3-69 
.FSS directive, 2-15 bit in KEY, 2-11 

JFNOPR, 3-69, 3-186 

G bit in KEY, 2-11 
(ce ee ener ee eter Se oR eee ane Oe Ce PS OA JFPRIV, 3-69, 3-70, 3-186 
General monitor directives, 3-1 to 3—9 bitin KEY, 2-11 

not used under RT-11, 3—1 JFSPRI, 3-69, 3-70, 3-186 

summary, 3-1 bit in KEY, 2—11 
General Register RO, 6—4 JFSYS, 3-69, 3-186 
.GETCOR, 7-33 bit in KEY, 2-11 
Get monitor tables JMPX, 3—5 

Part |, 3-394 Job 

Part Il, 3-396 aborting, 5—4 

Part Ill, 3-398 attaching to, 3-262 
GLOBAL, 3-5 context information, 2-11, 3-186 
Global symbols, 3-6 creating logged-in, 3~321, 3-323 
GLUN$, 5-31 creating logged-out, 3-320 
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Job (Cont.) 


definition, 2—8f 
detaching, 3-300 
general discussion, 1-5 
getting high limit, 7-35 
indication of login, 2-11 
killing, 3-268, 3-290 
new on system, 2-26 
parameters, 5-34, 5-38 
preallocate memory for, 2-19 
private maximum size, 5-24 
reattaching to, 3-263 
returning statistics on, 3-225 
returning status information on, 3-389 
suspending with SLEEP, 3-187 
suspending with .TWAIT, 7-62 
suspending with SPND$S, 5—56 
suspending with UU.STL, 3-382 
swap console with, 3-264 
swapping to disk, 2-11, 3-69, 3-186 
timing information on, 3—227 
Job area, 1-2, 2-8f 
JOBCNT, 3-397 
Job context information, 2-11, 2-26, 3-178 
Job header 
extended logical area, 2-15, 3-85, 3-235 
Job image 
changing size, 3-73, 7-33 
maximum size, 2-21 
minimum size, 2-21 
Job keyboard monitor, 2-25, 3-80, 3-178, 3-179, 
5-22, 7-31 
JOB MAX, 3-332 
Job space, 2-5 
JOBTBL, 3-395 
JSBTBL, 3-395 
JSR PC, substitute for, 3-5 


K 


Kernel mode 
Active Page Register (APR), 2-4, 3-137 
Kernel mode vector 
B.10, 2-22 
B.250, 2-22 
B.4, 2-22 
Kernel mode vector 244, 2-23 
Kernel mode vector 34, 2-23 
KEY, 2-25, 2-26 
clearing bits in, 3-69 
definition, 2-10 
low 512 bytes, 2—9f 
setting bits in JFLOCK, 3-185 
Keyboard 
disabling echo, 3-214 
enabling echo, 3-214 
forcing output, 3-216 
getting line from, 7-36 
ODT-mode input, 3-230 
reads, 3-165 
setting private delimiters for, 3-218 
special functions, 3-216 
writing data, 3-419 
Keyboard monitor, 1-1, 2-5, 2-16, 2-25, 3-233 
default, 1-5, 2-25, 5-22, 7-31 
entry, 2-25 
job, 2-25, 3-80, 3-178, 5-22, 7-31 
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Keyboard monitor (Cont.) 
prompts, 2-26 
system default, 3-80 
Keyboard monitor wait, 2-26, 3-168 
Keyword 
clearing bits in, 3-69 
setting bits, 3-185 
when refreshed, 2-10 
Killing a job, 3-268, 3-290 


L 


LAT, assign port, 3-117 

LAT, create port, 3-113 

LAT, deassign port, 3-120 

LAT, delete port, 3-115 

LAT, return port characteristics, 3-125 
LAT, return port status, 3-122 

LAT, show sessions, 3-131 


LB:, 3-235 
LBR, 1-3 
LIBR, 1-3 
Librarians, 1—3 
Library 
cluster, 1-3 
macro, 1-3 
object, 1-3 


resident, 1—3 
save image, 1—4 
universal, 1-3 
Line 
getting from terminal, 7-36 
width, 3—163 
Line counters, 3-196, 3—199 
Line delimiters, 3-165 
Line printer 
MODE values, B—6 
"no stall" option, 3-421 
RECORD values, B—-6 
writing data, 3-419 
LINK, 1-3, 1-4, 3-6 
Linker, 1-3 
RT-11, 2-9 
List 
logical names, 3-376 
Loader, 1-2 
Local data message 
receive, 3-108 
send, 3-104 
Locking disk blocks, 3-190 
Log, error, 2-20, 3-79 
Logged-in job 
create, 3-321, 3-323 
entry to keyboard monitor, 2-26 
Logged-out job 
create, 3-320 
entry to keyboard monitor, 2-26 
Logical names, 3-82, 3-92 
adding system-wide, 3-374 
assigning, 3-235 
deassigning, 3-245 
deassigning all, 3-243 
removing system-wide, 3-375 
Logical unit number 
assigning, 5—5 
getting information on, 5-31 
LOGIN, 1-5 


Login, indication of, 2-11 
Logins, 3-327 

disabling further, 3-343 

enabling, 3-409 

set number allowed, 3-332 
Logout, 3-267 

shutup, 3-302 
LOGOUT utility, 3-30 
.LOGS, 3-92 to 3-99 
LOGTBL offset, 6-12 
LOKFQ, 3-46 to 3-52 

disk directory lookup, 3-47 


disk wildcard directory lookup, 3-50 


/O support, 3-8 
Lookup 
directory, 3-38, 3-303 
special magnetic tape, 3-39 
LOOKUP, 7-39 
Low segment, 2-5, 2—-8f 
first 512 bytes, 2-9, 2-9f 
first 512 bytes for RSX, 4-9, 4—9t 
first 512 bytes for RT-11, 6-9 


M 


MAC assembler, 1-3, 4-1 
using general directives with, 3—1 
MACRO assembler, 1-3, 6-1 
using general directives with, 3-1 
Macro library, 1-3 
MAGLBL, 3-399 
Magnetic tape 
back spacing, 3-209 
CLUSTERSIZE values, B—4 
file characteristics word, 3-212 
get directory for, 3-37 
MODE values, B—4, B—-5 
reads, 3-165 
setting density, 3-209, B-5 
setting parity, 3-209, B-5 
skipping record, 3-209 


special directory lookup, 3-39, 3-305, 3-306 


special functions for, 3-209 
status word, 3-211 
writing data, 3-419 
writing end-of-file, 3-209 
MAKSIL, 1-4 
MAP$, 5-40 
MAPFQ, 3-154 to 3-159 
Mapping, 2-2 
address windows, 5—40 
physical memory, 3-157 
RDMEM privilege, 3-157 
resident library, 3-144, 3-154 
SYSMOD privilege, 3-157 
Masks 
private delimiter, 3—220t 
MAXCNT, 3-395 


-.MCALL, 4-2 
MEMLST, 3-395 
Memory 


changing allocation, 3-73 
changing size, 3-355 
expansion, 2-11 
increasing allocation, 5-24 
mapping, 2-2, 2—-4f 

page, 2-1, 2-2 


Memory (Cont.) 
poking, 3-352 
Memory management, 2-1 
I&D Space, 2-2 
MEMSIZ, 3-397 
.MESAG, 3-100 to 3-134 


.MESAG subfunction, send privileges, 3-110 


Message 
EMT logger, 3-109 
receive local data, 3-108 
send/receive, 3-100 
send local data, 3-104 

MFDPTR, 3-399 

Mnemonics, 3—6 

Mode 
ODT (one-character) input, 3-230 
tape, 3-229 


MODE modifier, OPEN FOR INPUT, 3—54 


MODE offset, 6—12 

MODE option, 3-24, 3-31 
disk, B—-1 
flexible diskette, B—3 
line printer, B—-6 
magnetic tape, B—4, B-5 
pseudo keyboard, B—-10 
terminal, B—7 

/MODE switch, 3-81, 7—11 

Monitor 
fixed locations for .PEEK, 3—-137t 


general RSTS/E directives, 1-4, 3-1 to 3-9 


RSX emulation, 4-2 
tables, 3-394, 3-396, 3-398 
Multicast addressing, 3-194 


Multiple private delimiters, 3-217 to 3-224 


Multiterminal service, 3—421 


N 


NAME, 3-77, 3-135 to 3-136 
Name program, 3-135 
NOCTLC offset, 6-12 
Non-file-structured |/O 

RSTS/E monitor, 4-2 


NRRTS, 2-25 
NULRTS, 3-399 


Object library, 1-3 
Octal Debugging Tool 
See ODT 


ODT (Octal Debugging Tool), 2-18, 2-20, 3-230, 


5-58 
ODT mode, 3-216, 3-230 
ODT-mode input, 7—59 
Offline, taking magnetic tape, 3-209 
ONLCLN, 3-341 
Open 
binary file, 3-18 
existing file, 3-53 
file, 3-23 
file or device, 3-53 
file-structured, 3-53 
LAT keyboard, 3—53 
non-file-structured, 3-53 
OPEN FOR INPUT, 3-53 
MODE modifier, 3-54 
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OPEN FOR OUTPUT, 3~23, 3-24, 3-31 
Open next disk file, 3-344 
OPNFQ, 3-53 to 3-58 
OPSER-based 
spooling package, 3-379 
ORG, 3-3 
requirement for, 3-4 


p 


P.2CC, 2-16f 
definition, 2—24 
P.BAD, 2—16f 


definition for asynchronous exceptions, 2-24 
definition for synchronous exceptions, 2-21 


P.BPT, 2-16f 
definition, 2-22 
P.CC, 2-16f 
definition, 2-24 
P.CRAS, 2-16f 
P.DEXT, 2-16f, 3-362 
definition, 2-20 
P.EMT, 2—-16f 
definition, 2-23 
P.FIS 
definition, 2-21 
PFLAG, 2-16f, 2-19, 2-23, 6-4 
combinations, 2-20 
definition, 2-18 
P.FPP, 2-16f 
definition, 2-23 
PIOT, 2—-16f 
definition, 2-22 
P.MSIZ, 2-16f, 2-21, 3-73, 3-362 
P.NEW, 2-16f, 3-179, 3-181, 5-22 
definition, 2-25 
P.OFF, 2—-16f 
definition, 2—18 
P.RUN, 2-16f 
.CCL passes control to, 3-64 
channel 17 open, 3-7 
definition, 2-27 
entry at, 2-10 
passing control, 3-182 
P.SIZE, 2-16f, 2-21, 3-73, 3-362 
P.STRT, 2-16f 
P.TRAP, 2-16f 
definition, 2-23 
Page, 2-1, 2-2 
Page Address Register 
See PAR 
Page Descriptor Register 


See PDR 
Paper tape punch, 3-419 
Paper tape reader 

reads, 3-165 
PAR (Page Address Register), 2—1, 2-2 
Parameter word, 3-320, 3-321 
Parity, setting magnetic tape, 3-209 
Password, changing, 3-290 
Password, set long, 3-290 
PAT (Patch Utility), 1-3 

object module, 1-3 
Patch Utility 


See PAT 
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PBS (Print/Batch Services) 
spooling package, 3-379 
PC (Program Counter), 2-5 
PDR (Page Descriptor Register), 2-1, 2-20 
PEEK, 3-137 to 3-138 
fixed monitor locations, 3-137 
PF.1US 
bit within P.FLAG, 2—-18f 
definition, 2-20 
PF.CSZ 
bit within PFLAG, 2—18f 
definition, 2—19 
PF.EMT, 2-23, 6—4 
bit within PFLAG, 2—18f 
definition, 2—18 
PF.KBM 
bit within P.FLAG, 2-18f 
definition, 2-20 
PF.NER, 2-20 
bit within PFLAG, 2—18f 
PF.REM, 2-20 
bit within PFLAG, 2—18f 
PF.RW, 2-20 
bit within PFLAG, 2-1 8f 
Physical addressing, 2—1, 2-2, 3-193 
Physical device name, 3-92 
Physical memory 
mapping, 3-157 
.PLAS, 3-139 to 3-162 
subfunction summary, 3-139 
.PLAS directive, 1-3 
.PLAS subfunctions, 3—139t 
Poking memory, 3-352 
/POSITION switch, 3-81, 7-11 
POSITN offset, 6-12 
.POSTN, 3-163 to 3-164 
PPN (Project-Programmer Number) 
assignable, 3-83 
entering user logical for, 3-235 
file specification, 3-83 
offset, 6-12 
wildcard lookup, 3-353 
Preallocate memory, 2-19 
Prefix EMT, 1—4, 2-18, 2-23 
PRINT, 7—41 
Print/Batch Services 
See PBS 
Priority, 2-11 
changing, 3-355 
run, 3-186 
Private delimiters 
and binary mode, 3-218 
characteristics, 3-218 
definition, 3-218 
keypad applications, 3-218 
masks, 3—220t 
system processing, 3-218 
Private memory maximum, 2-11 
Privilege 
permanent, 2-11, 3-70 
temporary, 2-11, 3-69, 3-186 
Privilege checking 
third-party, 3-413 
Privilege mask 
checking, 3-284 
Privilege name 
checking, 3-284 


Privileges 
clear current, 3—356 
read current, 3-356 
set current, 3-356 
Program 
maximum size under RSX, 5—24 
maximum size under RT-11, 6—10 
running, 3-182 
suspending, 3-187, 5-56, 7-62 
Program Counter 
See PC 
Program name, 3-135 
returned by .DATE, 3-77 
Program Status Word 


See PSW 
Project-Programmer Number 


See PPN 
Prompts 

keyboard monitor, 2—26 
PROTEC offset, 6-12 
Protection code 

default, 2-15 

file specification, 3-84 
/PROTECTION switch, 3-81, 7—11 
.PSECT, requirement for, 3—4 
Pseudo keyboard 

errors on output request, B—11 

MODE values, B—10 

reads, 3-165 

RECORD values, B—10 

special functions for, 3-214 

state change, 3-187 

writing data, 3-419 
Pseudovectors, 2-8, 2-16 to 2-30 

format with high segment, 2-16 
PSW (Program Status Word), 2-5, 6—4 
.PURGE, 7-42 


Q 


QIO$, 5-47 

QIOW$, 5-47 

Quota 
changing, 3-290 
detached job, 3-268 
disk, 3-268 


R 


-RCTRLO, 7-43 
RDBBK$, 5-52 
RDBDF$, 5-52 
RDMEM privilege 
mapping, 3-157 
Read 
device, 3-165 
file, 3-165 
ODT-mode, 3-230, 7-59 
-READ, 3-165 to 3-169 
RT-11, 7-44 
Read/write run-time system, 2-20 
-READC, 7-44 
Read-only run-time system, 2-20 
-READW, 7-44 
Reattach to job, 3-263 
Receive, 3-107 


Receive (Cont.) 


local data message, 3-108 
Receiver ID Block 

See RIB 
Record Management Services 


See RMS 
RECORD option, 3-167, 3-172, 3-416, 3-421 
flexible diskette, B—3 
line printer, B-6 
pseudo keyboard, B—10 
terminal, B—7 
RECORDSIZE option, 3—54 
Remove receiver, 3-103 
-RENAME, 7—46 
Rename file, 3-59, 7-46 
RENFQ, 3-59 to 3-60 
-REOPEN, 7—47 
REORDR, 3-29, 3-33, 3-58 
Reset channel, 3-61 
Resident libraries, I/O, 3-419 
Resident library, 1-3 
accessing, 3-139 
adding, 3-362, 3-366 
attaching to, 3-140, 5-8 
creating window, 3—144 
creating window to, 5-11 
detaching from, 3-149, 5-18 
eliminating window to, 3-151 
mapping windows to, 5-40 
maximum number, 5—8 
maximum number of, 3-140 
removing, 3-368 
special RSX directives, 5-52 
unloading, 3-369 
unmapping window from, 5-63 
Resident library, /O, 3-414 
Return LAT port characteristics, 3-125 
Return LAT port status, 3-122 
RETURN macro, 3-5 
Rewind tape, 3-209 
RIB (Receiver ID Block), 3-101, 3-102, 3-107, 3-109 
RMS (Record Management Services), 4—2 
/RONLY switch, 7-11 
RSTFQ, 3-61 to 3-62 
RSX 
emulation in the monitor, 3-144, 4-2 
environment, 4—1 to 4—10 
run-time system, 1—1, 1-2, 2-21, 4-2 
RSX directives, 1—4 
$C form, 4—6, 4-7 
expansions, 4-2 to 4-8 
$ form, 4-5, 4-6 
$S form, 4-7 
summary, 5—1t 
summary of, 5—1 
RSXMAC.SML, 4-2, 4-4 
RT-11 
environment, 6—1 to 6-13 
low 512. bytes for, 6—9 
run-time system, 1—1, 2-21 
scratch pad area, 6-10 
use of special prefix EMT, 2-19 
RT-11 directives, 1—4 
call formats, 6—5 
expansions, 6—4 
not processed on RSTS/E, 7—1 
summary of, 7—1 
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RT-11 run-time system 
illegal general monitor calls, 3-1 
.RTS, 3-178 to 3-181, 3-326 
RTSLST, 3-397 
.RUN, 3-182 to 3-184, 3-326 
hard errors, 3-183 
soft errors, 3-183 
Run-burst, changing, 3-355 
.RUN directive, 2-20 
Running a program, 3-182 
Run priority, 2-11, 3-186 
Run-time system, 2—8f 
adding, 3-362 
associating file with, 3-342 
capability defined, 2-18 
choosing, 1-2, 1-3 
default definitions, 2-18 
exit processing, 3-178 
general discussion, 1-1 to 1-5 
modifying, 2-12 
name returned, 3-77 
passing control to, 3-178 
removing, 3-364 
space taken by, 2-5 
top address, 1—4 
unloading, 3-364 
when removed, 2-20 
writing or modifying, 1-4 


S 


SATCTL, 3-395 
SATCTM, 3-395 
SATEND, 3-399 
Save Image Library 

See SIL 
SSAVESTATUS, 7-48 
.SCCA, 7-49 
SCCA$S, 5-54 
Scratch pad, 6-10, 7-53 

getting value from, 7-37 
Seize operation, 3-237 
Send local data message, 3-104 
Send privileges, .MESAG subfunction, 3-110 
SET, 3-185 
SETCC, 7-51 
Set device characteristics, 3-271 
SET directive, 2-10 
.SETFQB, 7-52 
SET JOB/KEYBOARD_MONITOR command, 3-178, 

7-31 

Set system default characteristics, 3-271 
Set terminal characteristics, 3-400 
SSETTOP, 7-53 
.SFPA, 7-54 
SFPA$, 5—55 
SHOW DISK command, 3-341 
Show LAT sessions, 3—131 
SHOW RUNTIME_SYSTEM command, 2-21 
Shut down system, 3-302 
Shutup logout, 3-302 
Significant event flag, 5-66 
SIL (Save Image Library), 1-4 
SILUS, 1-4 
Single event flag, 5-67 
Single-job monitor, 6—1 
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/SIZE switch, 3-81, 7—11 
CCL command, 3-65 
SLEEP, 3-187 to 3-188 
conditional, 3-187, 3-188 
Small buffers, 2-5 
Snap shot dump, 3-308, 3-351 
SNDLST, 3-397 
SP (Stack Pointer), 2-11, 2-22, 2-23, 2-24, 2-26 
SPEC, 3-189 to 3-215 
circuit counters, 3-195, 3-197 
disk, 3-190 
flexible diskette, 3-204 
line counters, 3-196, 3-199 
magnetic tape, 3-209 
multicast addresses, 3-194 
physical address, 3-193 
pseudo keyboard, 3-214 
terminal, 3-216 
Special prefix EMT, 1-4, 2-19, 2-23, 6-3 
SSPFUN, 7-55 
SPND$S, 5-56 
Spooling, 3-379 
Spooling package 
OPSER-based, 3-379 
PBS (Print/Batch Services), 3-379 
SSRESET, 7-57 
SST (Synchronous System Traps), 2-16 
SSTX$, 5-57 
Stack overflow, 2-11, 2-24 
Stack Pointer 
See SP 
Stack Pointer Register 


See SP 
Stall system, 3-382 
STAT, 3-225 to 3-226 
Statistics 
changing file, 3-266 
returning for job, 3-225 
Status, exit with, 5-23 
Status byte, 3-313 
STATUS variable, 2—28, 3-27, 3-33, 3-89 
Status word, magnetic tape, 3-211 
String 
display at terminal, 7—41 
scan for file name, 7-24 
Suspend 
job (with SLEEP), 3-187 
job (with .TWAIT), 7-62 
job (with SPND$S), 5-56 
jobs on system (with UU.STL), 3-382 
SVDB$, 5-58 
SVTK$, 5-60 
Swap console function, 3-264 
Swap file, 3-384, 3-386 
SWAP MAX, 3-355, 5-24 
Swapping, 2-11, 3-69, 3-186 
Symbol table file 
ERR.STB, 3-6 
Synchronous exception, 2-21, 5-58, 5-60 
Synchronous System Traps 


See SST 
$SYSMAC.SML 

system macro library, 6-3 
SYSMOD privilege 

mapping, 3-157 
SYSTAT, 3-135 


System default run-time system. 


See Default keyboard monitor 
System error log, 2-20 
System feature 
test, 5-30 
System feature labels, 5-29 
System macro library, 4-2 
$SYSMAC.SML, 6-3 
System-wide logical names 
adding, 3-374 
removing, 3-375 
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Tape 
See Magnetic Tape or DECtape 
Tape mode, 3-216, 3-229 
Task 
exit, 5-22 
Task Builder 
See TKB 
Temporary file, 3-30 
Temporary privilege, 3-186 
Tentative file, 3-61 
Terminal 
disabling, 3-290 
disabling echo, 3-214 
enabling echo, 3-214 
escape sequences mode, 3-219 
forcing output, 3-216 
getting line from, 7-36 
MODE values, B—7 
"no stall" option, 3—421 
ODT-mode input, 3-230 
reading low-speed tape on, 3—229 
reads, 3-165 
RECORD values, B—7 
setting characteristics, 3-400 
setting private delimiters for, 3-218 
special functions, 3-216 
TTSYNC characteristic, 3-219 
writing data, 3-419 
TFEA$, 5-62 
Time 
changing system, 3-298 
conversion, 3-295 
current, 5-36 
returning under RT-11, 7—20, 7-34 
slice, 2-4 
TIME, 3-227 to 3-228 
Timing, returning for job, 3-227 
TITLE, 3-3 
TKB (Task Builder), 1-3, 1-4, 3-6, 4-1, 4-3, 4-9 
TKB.TSK, 5-26 
TMPORG, 3-4 
Transfer request block, 2-12 
Transportable code 
RSX-11M-PLUS, 4-1 
RT-11, 6-1 
VAX/VMS under AME, 4—1 
Trap, 2-16 
asynchronous Ctr/C, 3-8 to 3-9, 5-54 
emulator, 2-18 
kernel mode address 10, 7—58 
kernel mode address 4, 7—58 
supervisor mode, 3-8 to 3-9 


TRAP instruction, 2-23 
.TRPSET, 7-58 
.TTAPE, 3-229 

undoing, 3-231 
TTDDT, 3-230 
.TTECH, 3-231 
TTINR, 7-59 
.TTNCH, 3-232 

undoing, 3-231 
.TTOUTR, 7-61 
TTRST, 3-233 
TTSYNC characteristic, 3-219 
TTYHCT, 3-397 
TTYIN, 7-59 
.TTYOUT, 7-61 
.TWAIT, 7-62 
Type-ahead 

canceling, 3-216 


U 


UCTTBL, 3-399 

UFD (User File Directory), 3—25 
deleting, 3-411 
positioning on disk, 3-348, 3-350 
preextending, 3-348, 3-350 

.ULOG, 3-234 to 3-247 
subfunction summary, 3-234 

.ULOG directive, 2-15 

UMAP$, 5-63 

UMPFQ, 3-161 to 3-162 

Universal library, 1-3 

Unmapping address window, 3-161, 5-63 

UNORG, 3-4 

Unstall system, 3-382 

UNTCLU, 3-395 

UNTCNT, 3-395 

UNTERR, 3-899 

UNTLVL, 3-399 

UNTOPT, 3-395 

User File Directory 


See UFD 
User job area, 1-2, 2-8f 
User job image, 2—-8f 
changing size, 3-73 
definition, 2-5 
expanding, 5—24 
maximum size, 2-21 
minimum size, 2-21 
preallocate memory for, 2-19 
User logical, 3-85 
assigning, 3-234 
deassigning, 3-234, 3-245 
deassigning all, 3-243 
destroyed, 2-25 
entering, 3-234 
listing, 3-234 
User mode 
Active Page Register (APR), 2-4 
User stack area, 2-11 
USRLOG 
within low 512 bytes, 2—10f 
USRPPN, 3-83, 3-85, 3-235 
within low 512 bytes, 2—-10f 
USRPRT, 3-85, 3-235 
within low 512 bytes, 2-10f 
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USRSP, 2-25 Virtual disk, creating/deleting, 3-372 
definition, 2-11 


low 512 bytes, 2—9f W 
USTAT byte, 3-304 
UU.3PP, 3-413 WAIT, 7-63 
UU.ACT, 3-251 WCB (Window Control Block), 3-311 
UU.ASS, 3-235 to 3-242, 3-252 WDB (Window Definition Block), 5—65 
UU.ATR, 3-254 WDBBK$, 5-65 
UU.ATT, 3-262 WDBDF$, 5-65 
UU.BCK, 3-266 Wildcard 
UU BYE, 3-267 account read and reset, 3-358 
UU.CCL, 3-269 file lookup, 3-46, 3-336 
UU.CFG, 3-271 PPN (Project-Programmer Number) lookup, 3-353 
UU.CHE, 3—282 Window 
UU.CHK, 3-284 creating, 5—11 
UU.CHU, 3-290 eliminating, 3-151, 5-20 
UU.CNV, 3-295 mapping, 3-154 
UU.DAL, 3-243 to 3-245, 3-297 mapping to, 5—40 
UU.DAT, 3-298 maximum number of, 3-144 
UU DEA, 3-245 to 3-247, 3-299 resident library, 3-144 
UU.DET, 3-300 unmapping from, 3-161, 5-63 
UU.DIE, 3-302 Window Control Block 
UU.DIR, 3-303 See WCB 
UU.DLU, 3-307 Window Definition Block 
UU.DMP, 3-308 See WDB 
UU.ERR, 2-22, 2-25, 3-309 Window ID 
UU.FCB, 3-311 returned by CRAFQ, 3-148 
UU.FIL, 3-315 returned by CRAW§$, 5-14 
UU.HNG, 3-319 used by ELAFQ, 3-151 
UU JOB, 3-320 to 3-326 used by ELAW$, 5-20 
UU.LIN, 3-326, 3-327 used by MAPFQ, 3-155, 3-158 
UU.LOG, 3-332 used by UMAP$, 5—63 
UU.LOK, 3-334 . used by UMPFQ, 3-161 
UU.MNT, 3-338 WRITA, 3-414 to 3-418 
UU.NAM, 3-342 WRITC, 7-64 
UU.NLG, 3-343 WRITE, 3-419 to 3—423 
UU.ONX, 3-344 RT-11, 7-64 
UU.PAS, 3-348 Writing, 3-414, 3-419 
UU.POK, 3-352 one character, 7—61 
UU.PPN, 3-353 .WRITW, 7-64 
UU.PRI, 3-355 WSIG$, 5-66 
UU.PRV, 3-356 WTSE$, 5-67 
UU.RAD, 3-358 
UU.RTS, 3-362 to 3-373 X 
UU.SLN, 3-374 
UU.SPL, 3-379 XBUF (Extended Buffer Pool), 2—4f 
UU.STL, 3-382 XRB, 2-12 
UU.SWP, 3-383 clearing under RT-11, 7-10 
UU SYS, 3-389 data returned to, 3—7 
UU.TB1, 3-394 low 512 bytes, 2-9f 
UU.TB2, 3-396 mnemonics assigned to, 2-13 
UU.TB3, 3-398 P.NEW entry, 2-26 
UU.TRM, 3—400 P.RUN entry, 2-28 
UU.YLG, 3-409 presetting to zero, 3-6 
UU.ZER, 3-411 routine to clear, 3—7 
.UUO, 3-248 to 3-413 size of, 2-13 

subfunction summary, 3—248t XRB format, 2—14f 
UUOFQ, 3-63 

Z 

V Zero device, 3—411 
V1.., 7-66 
..V2.., 7-66 


Version 1 RT-11, 7-66 

Version 2 RT-11, 7-66 

Vertical format, control characters, 5—49t 
Virtual addressing, 2-1, 2-2 
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How to Order Additional Documentation 


Technical Support 


If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 


your electronic, telephone, or direct mail order. 


Electronic Orders 


To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud 
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location 


Continental USA, 
Alaska, or Hawaii 


Puerto Rico 


Canada 


International 


Internal! 


Call 
800-DIGITAL 


809-754-7575 
800-267-6215 


Contact 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, New Hampshire 03061 


Local Digital subsidiary 


Digital Equipment of Canada 

Attn: DECdirect Operations KAO2/2 
P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 


Local Digital subsidiary or 
approved distributor 


USASSB Order Processing - WMO/E15 
or 

U.S. Area Software Supply Business 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


1For internal orders, you must submit an Internal Software Order Form (EN-01740-07). 
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